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PREFACE 



MANUAL OBJECTIVES 

The SPM-llNI Reference Manual is a manual describing the 
structure and use of the SPM-llM software supported by DIGITAL 
on RSX-llM operating systems. 

INTENDED AUDIENCE 

This manual is for all users of SPM-llM. 
STRUCTURE OF THIS DOCUMENT 

Chapter 1 is an overview of the architecture of SPM-1 IM . 
Chapter 2 describes the components of SPM-llM. 
Chapter 3 describes how to use SPM-llM. 

Chapter 4 describes data collection and reduction procedures. 

Chapter 5 describes how to read the performance report. 

Chapter 6 delineates the resources used by SPM-llM. 

Chapter 7 is the usage notes for SPM-llM. 

Appendix A is a specification of the Hook Records. 

Appendix B is a specification of the Monitor Parameter Block 
(MPB) . 

Appendix C is a specification of the Information Records. 

Appendi X D is a s pec i f i c a t i o n of the System Metrics Record . 

Appendix E is a specification of the logfile format. 

Appendix F is a sample performance report. 

Appendix G is a sample SMPGEN.CMD procedure. 
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Chapter 1 
OVERVIEW OF SPM-11M 



The Software Performance Monitor (SPM-llM) is a software 
instrument used to measure the performance of a computer system 
running the RSX-llM operating system. 

SPM-llM is a natural counterpart to RSX-llM: while RSX-llM 
manages the resources of the computer system , SPM-llM remembers 
how the resources were used over a period of time, similar to 
the way a tape recorder remembers a set of sound patterns. 
Moreover, SPM-llM has the capability of "playing bac k" these 
recordings of resource usage, so an analyst can study how and 
when the resources were used. 

SPM-llM is a n event driven performance monitor. As each event 
of interest occurs, the performance monitor is called. 



1.1 RESOURCES 

The key resources of interest are: 

• CPU 

• Main memory 

• I/O devices 

• File system 

• Task loader 

Note that a resource can be a hardware resource -- such as the 
CPU, main memory or an I/O device; or a software resource -- 
such as the file system or the task loader. 
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1.2 USERS 



A user is the entity which uses the resources managed by the 
operating system. We define a user to be an RSX-llM task. Of 
primary concern is the workload the task places on the system , 
that is, how much and for how long the resources are used. To 
describe a task's workload we will define a set of metrics for 
resource usage. 



1.3 RESOURCE MODEL 

Because a number of tasks may concurrently request the use of a 
resource, and only one task may use the resource at a time, a 
queue will form for the resource. A simple queued resource is 
depicted as follows: 



w u 
< s > 



The vertical bars represent the queued resource requests and 
the square represents the resource. Three interval s are shown 
on the diagram. "W" denotes the interval during which a task 
is waiting for the resource. "U " denotes an interval when a 
task is using the resource. "S" is the sum of "W" and "U", 
called the service time. 



1.4 EVENTS 

The activity of the RSX-llM operating system can be traced by 
defining a set of key events and recording a set of raw infor- 
mation associated with each event . The events of interest are 
those which capture the metrics of resource usage. 

For exampl e , we may want to know how 1 ong a task waits for the 
disk, how many times it uses the disk and how long it uses the 
disk. The following events are defined to capture the I/O 
activity: 

1. Queue I/O packet to driver 

2. Driver gets I/O packet 

3. Driver posts I/O completion 



7/81 



OVERVIEW OF SPM-llM 



1-2 



1 



Applied to the queued resource model for the disk, these I/O 
events appear as follows: 



The complete set of events defined for RSX-llM is specified in 
Appendix A. 



1.5 TASK METRICS 

The task metri cs quantify the workload that individual tasks 
place on the system. 

The task metrics are computed for all three types of intervals: 
U, W and S . The performance report will contain a line of task 
metri cs for each resource used by the task. The task metrics 
are : 

• Count 

A s impl e metric for resource usage is a count of the 
number of times the resource was used during the 1 i f e 
of a task. For example, if a task does four QIOs to a 
disk, the I/O request count is four. 

§ Total Time 

Another simple metric is how long the task uses a 
resource. For example, if a task did four QIOs and 
the I/O requests took 20ms , 60ms, 10ms and 50ms to 
complete, the total usage time would be 140ms. 

• % Resident Time 

Also of importance is what percentage the total usage 
time 1 s of the time the task was i n memory. For 
exampl e , 1 f the prev i ous task was in memory for one 
second the percentage of resident time spent using the 
disk was 140ms/1000ms *100% = 14%. 
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• Interval St at i sties 

The statistical nature of the usage time is of key 
importance . 

The metrics defined for interval statistics are: 

Minimum interval 

Mean (average) interval 

Maximum interval 

Coefficient of Variation 

The coefficient of variation is the standard deviation 
of the intervals divided by the mean interval. 

The coefficient of variation is of particular impor- 
tance because it tells whether the data is clustered 
about the mean (small c.v.) or widely scattered about 
the mean (large c.v.) . I n fact , if the c.v. is 1 arge , 
the mean may tell very little about the nature of the 
data , since very small values and v ery large values 
may combi ne to produce a mean which is not represen- 
tative of any real value. 



1.6 SYSTEM METRICS 

The task workl oad metrics defined above are useful for deter- 
mining who is using the system resources and how much each user 
is consuming. 

Also of importance is the performance of the system as a whole. 
To this purpose we define a set of system metrics. 

The system metrics vary as a function of time. To see how a 
given system metr i c vari es with time, h i stogr ams are computed 
for the metri c . Each h i stogram describes the per cent usage of 
a resource for one sampling interval. The sampling interval is 
a settable parameter described in Chapter 3, section 3.2.1. 



CPU 



The CPU can be in one of three general states: 



User 



Kernel (system) 



Id! e 
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A useful metric is the per cent of time spent in each state, 
that is: 

t % time in user state 

t % time in kernel state 

• % time in idle state 

This gives us a general picture of how effectively the CPU is 
being uti 1 i zed (% time in user state + % time in kernel state), 
as well as the overhead imposed by the operating system (% time 
in kernel state). 

Memory 

On RSX-llM the memory space is divided into partitions. The 
user can select one system-controlled partition for monitoring 
by SPM-llM. The performance monitor will compute the per cent 
of the partition that was in use at the end of each sampling 
interval and print a histogram. 

The user will most commonly select the partition "GEN" for 
mon i tor i ng . 

I/O Devices 

The user can select one I/O device to be monitored by SPM-llM 
for system-wide usage . SPM-llM wi 1 1 compute the percent of 
time the device was uti 1 i zed for each sampl i ng interval and 
print a histogram. If the device is mounted Files-11, SPM-llM 
will compute the percent disk space used at the end of each 
sampling interval and print a histogram. 

Pool 

The RSX-llM system pool contains the dynamical ly al 1 ocated data 
structures used by the executi ve . SPM-llM will compute the per 
cent of pool that was in use at the end of each sampl i ng 
interval and print a histogram. 

Chec kpoi nt file(s) 

SPM-llM wi 1 1 monitor checkpoint files allocated by the ACS 
command. The performance monitor will compute the per cent of 
all active checkpoint file space in use at the end of each 
sampling interval and print a histogram. 
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Chapter 2 

QQj^PONENTS 
OF SPM-11M 



The SPM-llM performance monitor consists of two main compo- 
nents: the Data Collection Component and the Data Reduction 
Component. The Data Collection Component records the resource 
usage events of the operating system to a logfile; the Data 
Reduction Component reads the logfile and produces a perfor- 
mance report suitable for analysis. 

This general architecture is depicted in Figure 1. 



RSX-11M 



Data 
Collection 
Component 



LogFile 



Data 
Reduction 
Component 



Performance 

He port 



Figure 1 
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By decoupling the Data Collection Component from the Data 
Reduct i on Component in time, the performance monitor can 
collect detailed information about a huge number of events, 
albeit in a raw format. The Data Reduction Component can then 
be used to selectively analyze and filter the i nf ormati on in 
the logfile to produce a performance report. This architecture 
shifts the computational aspects of the performance monitor 
from the Data Collection Component to the Data Reduction 
Component. The benefit derived is that the performance monitor 
uses less CPU time, thus minimizing its i nterf erence with the 
CPU. The cost is more I / act i v i ty , whi ch in most systems can 
be d i rected to a secondary mass storage device not in the path 
of the major stream of I/O act i v i ty . 



2.1 DATA COLLECTION COMPONENT 

The Data Col 1 ection Component consists of both software and 
hardware distributed in various places within a n RSX-llM 
system. 

The basic pieces of the Data Collection Component are: 

• Hooks 

• Hook Dispatcher 

• Hoo k Routines 

• Hook Records 

• KWll-P Clock and Handler 

• Hook Buffers 

• Logfile 

• Data Collection Task (...COL) 

• Termi nat i on Task ( . . . TRM) 

• COL Message Task (COLMSG) 



The relationship between these pieces is shown in Figure 2. 
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DATA COLLECTION COMPONENT 



BSX-1 1M 



BSD 
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BUFFER 
PARTITION 



Hook 
Record 



lO 



LOGFILE 



Fi gure 2 



Heuristic Procedure for Data Col 1 ecti on 



At this point a heuristic procedure for data collection will be 
given, although the terms used in the procedure have not been 
prec i sel y def i ned . 
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When a resource usage event occurs in RSX-llM, the corre- 
sponding hook calls the hook di spatcher , which uses the hook ID 
to call the appropriate hook routine. The hook routine 
collects information relevant to the hook and assembles it into 
a hook record, which resides in a hook buffer. When a hook 
buffer is filled with hook records, it is written to the 
logfile. The logfile is closed at the end of the measurement 
interval , and subsequently reopened by the Data Reduct i on 
Component . It read s the hook records and uses them to der i ve 
the resource usage metrics and print a performance report. 

The detai 1 s of these pieces will now be developed more fully. 



2.1.1 Hooks 

A hook is simply an implementation technique for capturing a 
resource usage event. For SPM-llM, a hook is implemented as a 
subroutine call inserted at the point in the operating system 
where the event occurs. The subroutine call passes control and 
one argument, the hook ID, to the hook dispatcher. The form of 
an SPM-llM hook is as follows: 

CALL @$HKDSP 
.WORD H$XXXX 

where XXXX is mnemonic identifying the particular hook. A 
complete specification of all hooks is given in Appendix A. 



2.1.2 Hook Dispatcher 

Hooks are resident within the operating system; their method of 
i nserti on is addressed in Chapter 3, sect i on 3.1.3. However , 
most of the code and database for the Data Collection Component 
is not resident within the RSX-llM executive. 

The bulk of the data collection code is resi dent in the data 
col 1 ecti on task called COL (taskname is ...COL). The chief 
benefit derived from this design is that only a small amount of 
execut i ve space ( whi ch transl ates di recti y to the critical 
resource: pool) is used by the performance monitor. 

The purpose of the hook dispatcher is to map and call the hook 
routi nes which are resident in the COL task. Note that , though 
the hook routines are resident in the task partition for COL, 
they are executed in the context of a directive or interrupt 
servi ce rout i ne . The hook di spatcher is resident in pool , is 
allocated when COL is activated, and is deallocated when COL 
exits. The hook dispatcher is analagous to an ICB for a 
loadable driver. 
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A one word dispatch vector labelled $HKDSP is added to system 
common (SYSCM). This word points to the entry point in the 
hook dispatcher resident in pool . It is the port through which 
all hooks pass control from, the RSX-llM executive to the Data 
Collection Component of the performance monitor. 



2.1.3 Hook Routine 

A hook routi ne copies i nf ormation which is general 1 y scattered 
about the executive (typically in SYSCM or SYSTB) into a hook 
record which is resident in a static common or dynamic region. 
A timestamp is also recorded in the hook record. 

There are two general types of hooks : task and system . The 
task hooks collect data relevant to resources used by tasks ; 
the system hooks collect data which is system-wide (e.g., % CPU 
time in user, kernel and idle). 



2.1.4 Hook Record 

The information collected at each hook is formatted into a hook 
record . The hook record provides a n identical representation 
of a hook's information content both in memory and in the 
1 ogf i 1 e . 

Each hook record contains both generic and hook- spec i fi c data. 
Generic data applies to all hooks. Generic data consists of: 

• Hook ID 
t Taskname 

• Timestamp 

Task' s TI (UCB address) 

Hook specific data a p p 1 i e s to only one or a smal 1 subset of the 
hooks. For example, the H$CDRP (call directive processor) hook 
records the directive ID cade as hook-specific data. 

Appendix A specifies the information content of the hook 
records . 
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2.1.5 KWll-P Clock and Handler 



For preci se performance measurements , SPM-llM needs a high 
speed clock runni ng i ndependent of the RSX-1 IM system clock. 
It is therefore a requi rement that a KWll-P clock be i nstal 1 ed 
on a machi ne runni ng SPM-llM. Thi s KWll-P clock must be in 
addition to the RSX-llM system clock, be it a KWll-L or KWll-P. 

The KWll-P is i niti al i zed by the COL task to run at 100 kHz 
(10 microsecond ticks) and to i nterrupt every 65536 ticks 
(approximately every 0.65 second). 

The KWll-P clock time is mai ntai ned as as 2 word (32 bit) value 
which, at a rate of 100 kHz, will overflow in a little over 8 
hours. 

To preclude the possibility of overflow of the KWll-P clock 
time, a maximum measurement interval of 8 hours has been 
establ i shed. The task COL enforces this by setting an 8 hour 
mark-time when activated. If the timer ex pi res , COL wi 1 1 stop 
data col 1 ection and exit. 

The COL task allocates a piece of system pool and links it to 
the KWll-P clock vector. Thi s pool node serves as the clock 
interrupt handl er , which updates the high order clock time 
1 ocated i n SYSCM at $PCLKH. The 1 ow order clock time is not 
stored in memory; rather, each hook routine copies the c urrent 
contents of the KWll-P clock's count register to the hook 
record directly to get the low order time word. 



2.1.6 Hook Buffer 

Hook records are stored in buffers which are resident in either 
a static common or a dynami c reg ion. When a hook buffer is 
full, the hook routine sets an event flag which signal s the COL 
task to write the buffer to the logfile. 

The hook buffers are 1 i nked together into a circular list. 
There may be from 2 to 8 buffers in a list, and all the buffers 
must be of the same length. A buffer may be from 256 words to 
4096 words long. 

If the buffers are resident in a static common, the maximum 
si ze common whi ch can be used is 4096 words . Thi s 1 imi tati on 
is imposed because the COL task uses one APR to map the static 
common . 

If the buffers are resident in a dynamic region, the region can 
be from 256 words to 32K words long. 
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2.1.7 Logfile 

The logfile contains four types of records : 

• Monitor Parameter Block (MPB) 

• Information Records 
8 Hook Record s 

• System Metric Records 

See Appendix E for a specification of the logfile. 



Monitor Parameter Block 

The Monitor Parameter Block (MPB) is used by the COL task to 
initialize its measurement parameters . The MPB is formatted as 
an Information Record with record type I$MPB. A detai 1 ed 
description of the MPB is given in Append i x B . 

The MPB is generated by a command f i 1 e cal 1 ed SMPGEN.CMD. See 
Chapter 3 , section 3.2.1 for detai 1 s . 



Information Records 

The Information Records are used to supplement the Hook Records 
in the logfile with system context useful to the Data Reduction 
Component . 

When COL starts up it reads the MPB from the MPB file and 
writes it to the 1 ogf i 1 e. Fol lowing the MPB , COL writes a 
stream of Information Records which contai n a number of RSX-1 IM 
data structures defining the initial system state. These data 
structures are: 

• Task Control Bl ock (TCB) 

• Partition Control Block (PCB) 

• Device Control Block (DCB) 

• Unit Control Block (UCB) 

Each data structure is copied to a separate Information Record. 

When COL begins a measurement interval (starts data collec- 
tion), it records the RSX-llM system time as well as the 
SPM-llM time (KWll-P time) to an Information Record (I$TMR). 
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When COL ends a measurement interval (stops data collection) it 
copies the RSX-llM system time, SPM-llM time, CPU time accrued 
in kernel state and CPU time accrued in idle state to an 
Information Record (I$STM). 

A compl ete specification of al 1 Information Records is given in 
Appendix C. 



Hook Records 

As each hook point is encountered in the executive, a Hook 
Record is written to the logfile. See section 2.1.4 for 
detai 1 s . 



System Metri cs Record 

At the end of each sample interval , a System Metrics Record is 
wr i tten to the logfile. Thi s record contains i nf ormat i on whi ch 
describes the system-wide usage of the selected resources. 

The System Metri cs Record is speci f i ed in Append i x D. 



Logfile Media 

The logfile can be resident on disk as a Files-11 file or on 
magtape as a sequence of tape records. 

If the 1 ogf i 1 e is resident on disk, it consists of a sequence 
of V i rtual blocks ( v i rtual bl ock = 256 word s) . The records 
within these virtual blocks are def i ned accord i ng to the record 
definitions for the MPB, Information Records, Hook Records and 
System Metric Records . Note that the logfile does not have any 
other record structure (such as FCS or RMS type records) . 

If the 1 ogf i 1 e is on a magtape, the MPB , Information Records 
and Hook Records are imbedded in a stream of tape records . 
Each tape record is equal in length to a hook buffer. 



2.1.8 Data Collection Task (...COL) 

This section gives a functional descri pti on of the COL task . A 
guide to using COL is provided in Chapter 3, section 3.2.2. 

As noted before , this task contains both code which executes in 
executive context (as a directive or interrupt process) and 
code whi ch executes in the context of a pri v i 1 eged task. The 
code which executes at executi ve level is the hook rout i nes . 
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2.1.8.1 COL Executive Level Code - 

The hook routines were made a part of the COL task for a number 
of reasons : 

• They must be resident in some partition outside of 
executive space . 

• They can easily be loaded as part of the COL task. 

• They impl ement routi nes which are common to hooks and 
to the COL task. 



2.1.8.2 COL Task Level Code - 

Most of the COL task consists of code which is executed at task 
level. The major functions of the COL task are: 

• In i ti al i zati on 

• Starti ng data col 1 ecti on 

• Writing to logfile 

• Stopping data collection 
Cleanup 

2.1.8.2.1 Initial i zati on - 

When COL begins execution , there is very little SPM-llM code 
el sewhere in the system. All that exi sts are the hooks in the 
executive which all call a dummy return subroutine in SYSXT. 
It is the job of COL to initialize all code and databases 
requi red for the SPM-llM performance monitor. The specific 
sequence of initialization functions performed by COL are: 

• Read MPB file and store MPB in COL buffer. 

• Create dynami c region (if necessary) and set up ring 
of hook buffers. 

• Write MPB and Inf ormati on Records (RSX-llM data 
structures) to logfile. 

• Mark COL task as fixed in memory and nonshuf f 1 abl e . 

• Initialize hooks specified in MPB. 
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• Allocate pool node for hook dispatcher and copy code 
to pool node. 

• Allocate pool node for KWll-P clock handler and copy 
code to pool node. Link pool node to KWll-P clock 
vector. 

• Initialize KWll-P clock and turn it on. 

• Initialize measurement parameters as specified in MPB. 



2.1.8.2.2 Starting Data Collection - 

When data collection is disabled, the hook dispatch vector 
$HKDSP points to a dummy routine in SYSXT which simply steps 
over the hook ID and returns to the i nstructi on in the 
execut i ve f ol 1 owi ng the hook . 

Just prior to starting data collection, COL writes a " start 
data collection" Information Record (I$TMR) to the hook buffer. 

To enabl e data collection the COL task simply points the hook 
di spatch vector $HKDSP to the hook di spatcher code resident in 
pool . 



2.1.8.2.3 Writing Hook Records to Logfile - 

The steady state function of the COL task is to write Hook 
Records to the logfile. When a hook routine fills a hook 

buffer, it sets an event flag for COL which wakes COL from its 
wait state. COL then writes the hook buffer to disk or magtape 
(waiting for completion of the write), and loops to see if 
another hook buffer is ready to write. When no more hook 
buffers are outstanding, COL returns to the wait state. 

If the hook buffers fill up too rapidly for COL to write them 
to the 1 ogf i 1 e , COL wi 1 1 set the overfl ow status bit. If the 
overf 1 ow status is set when a measurement interval ex pi res , COL 
will print a status message on the consol e device (CO: ) . In 
general , the data coll ected during a measurement interval 
should not be used for data reducti on if the overflow condition 
occurred. 



2.1.8.2.4 Stopping Data Collection - 

To stop data col 1 ecti on , COL merel y poi nts the hook di spatch 
vector $HKDSP to the dummy routine at $HKEXT in SYSXT. It then 
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writes a stop data collection Information Record (I$STM) to the 
hook buffer. Any outstanding records in the hook buffer will 
be written to the logfile. 



2.1.8.2.5 Cleanup - 

Before COL exits, it must release any system resources it has 
allocated and deactivate any hardware it has turned on. The 
following actions are thus performed: 

• Turn off KWll-P clock. 

• Deallocate pool nodes for hook dispatcher and KWll-P 
clock handler. 

• Unfix COL task. 



2.1.9 Termination Task (...TRM) 

The purpose of the termination task (...TRM) is to signal the 
COL task to stop data collection and exit. TRM provides a way 
to manually termi nate the COL task , as opposed to automatic 
shutof f by t imeout or buffers ( see Chapter 3, secti on 3.2.1). 



2.1.10 COL Message Task (COLMSG) 

The COL message task contai n s the ASCI I text for the error 
messages issued by the COL task . If the COLMSG task is i nstal - 
led and a COL error occurs, the full error message text will be 
pri nted . If a COL error occurs and the COLMSG task is not 
i nstal 1 ed , the COL task wi 1 1 pri nt an error number whi ch can be 
correlated with the correct error message in Chapter 3, section 
3.2.2. 



2.2 DATA REDUCTION COMPONENT 

The mai n purpose of the Data Reduction Component is to read the 
raw data from the logfile (hook records) and produce a perfor- 
mance report detail i n g the resources used by the various tasks 
in the system. 

The Data Reduct i on Component accompl i shes this in a multi-step 
process involving two tasks: 

• Monitor Data Reduction (MDR) Task 

9 DRS Task 
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There are three major steps in the data red uct i on process : 

1. Map Hook Records to Task Workl oad Records and generate 
system-wide metrics sect i on of performance report (MDR 
Pass 1). 

2. Sort Task Workl oad Records (DRS). 

3. Summarize Task Workload Records and generate task 
metrics section of performance report (MDR Pass 2). 



The Task Workl oad Records are 1 ntermedi ate data structures 
which contain the data collected for each task and each 
resource used by the task. 

This general procedure is depicted in Figure 3. 



DATA REDUCTION COMPONENT 






Figure 3 
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From the figure we see there are four databases which are 
processed by the two tasks: 

• TRACE.LOG (logfile containing Hook Records). 

• RESOURCE. TMP (intermediate file containing unsorted 
Task Workload Records). 

• RESOURCE. SRT (intermediate file containing sorted Task 
Workload Records. 

• REDUCE. RPT (final performance report). 



2.2.1 MDR Pass 1 

MDR reads hook records from the 1 ogf i 1 e (default name is 
TRACE.LOG) and maps the information to the Task Workload 
Records in the intermediate file RESOURCE . TMP . 



2.2.2 DRS Pass 

DRS sorts the Task Workload Records using the following three 
keys : 

• Generic Taskname 

• Task's TI UCB address 

• Task start time. 



NOTE: By "generic taskname" we mean the installed taskname of 
a multiuser task . For example, the generic taskname for 
the task PIPT5 is ...PIP. If the task is not multiuser, 
generic taskname is simply the run time taskname. 



The three keys listed above are concatenated into one "big" 
key , with the generic taskname forming the highest order part 
of the key, the Task's TI UCB address forming the middle order 
part of the key, and the Task start time forming the low order 
part of the key. The DRS task sorts al 1 the Task Workload 
Records using this one big key. With this technique the DRS 
task only needs to do one sort operation on the file 
RESOURCE. TMP. 
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When DRS is done sorting the Task Workload Records, the records 
will be arranged as follows: 

• All records with the same generic taskname will be 
clustered together. 

• Within a generic taskname cluster, all records with 
the same TI will be clustered together. 

• All records within a taskname-TI cluster will be 
sequenced by ascending task start time. 

DRS writes the sorted Task Workload Records to the file 
RESOURCE. SRT. 



2.2.3 MDR Pass 2 

MDR reads the Task Workload Records from RESOURCE. SRT and 
generates a performance report . A description of the 
performance report is given in Chapter 5. 
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Chapter 3 
GUIDE TO USING 
SPM-11M 



3.1 INSTALLATION 



3.1.1 SPM-llM Kit 



The SPM-llM kit is distributed on 800 BPI magtape. It contains 
all the files necessary to install and use SPM-llM. The files 
are in DOS tape format. When copied to disk, the files will 
occupy approximately 800 disk blocks. 

The command file PMONCPY.CMD can be used to copy the kit files 
from tape to tape, tape to disk, disk to tape or disk to disk. 
All files are contained in the directory [11,2]. The contents 
of the kit are : 



Component 



File 



Kit c p y CO mm and file 
SPM-llM mi n 1 - reference guide 
MPB GEN command file 
Macro definition prefix file 
Executive source correct i on 
Executive source correcti on 
FllACP patch command file 
FllACP patch source 
COL/TRM build command file 
COL V er 1 ay doscri ptor file 
COL/TRM object 1 ibrary 
MDR object library (EIS version) 
MDR object library (FPP version) 
MDR/CLF build command file 
Data reduction sort task 
DRS map file 
DRS sort command file 
CLF task 
CLF map file 



command file 
files 



PMONCPY.CMD 

SPM.DOC 
SMPGEN.CMD 

HKMAC.MAC 
PMONSLP.CMD 

* . COR 

PMONPAT.CMD 

DISPAT.PAT 

PMONBLD.CMD 

COLBLD.ODL 
COL.OLB 
MDREIS.OLB 
MDRFPP.OLB 
MDRTKB.CMD 
DRS.TSK 
DRS. MAP 
DRS. CMC 

CLF.TSK 
CLF. MAP 
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3.1.2 Prerequisites to Installing SPM-llM 
COL Prerequisites 

The following are the prerequi sites for running the COL task : 

• Mapped System 

SPM-llM can only be installed on a mapped RSX-llM 
system. 

• Get Partition Parameters Directive 

The COL task will only work if support for the Get 
Partition Parameters (GPRT$) directive is generated 
into the executive. 

• AST Support 

The COL task will col 1 ect System Metrics only if AST 
support is generated into the executive. 

• Send and Receive 

The COL task will issue full ASCI I error message text 
via the error message task COLMSG if support for Send 
and Receive is generated into the executive. 

• PLAS Support 

I f PLAS support is not generated into the execut i ve , 
the COL task buffering is limited to a maximum of a 4K 
word static common. 

If PLAS support is generated into the executive, the 
COL task buffering may be in a dynamic region up to 
32K words 1 ong . 



MDR Prerequisites 

MDR requires the following features of the system where it is 
run : 

• EIS instructions 

8 support for the executive directives: ASTX$, EXTK$, 
GPRT$, GTSK$. 

« checkpointing to a dynamically allocated system 
checkpoint file. 
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t any features needed by the SYSLIB routines CSI$, 
GCML$, and FCS. 



3.1.3 Install ing SPM-llM 

To install SPM-llM, you must start with: 

• An RSX-llM V3.2 distribution kit 

§ An RSX-llM autopatch kit at the current level 

• An SPM-llM distribution kit 



To i nstal 1 SPM-llM you must perform an RSX-llM SYSGEN. A 
SYSGEN is required because source code for SPM-llM is inserted 
into the RSX-llM sources. SPM-llM source code is added to the 
following RSX-llM source modules: 

SPM-llM Function RSX-llM Modules 

SPM-llM Macros and Definitions RSXMCO.RSXMC 

Hooks DRDSP,DRQIO,DREIF,DREXP, 

DRREG,REQSB,SYSXT, lOSUB, 

LOADR 

Additional Stack Space LOWCR 
Common Database SYSCM 
Dummy Hook Return Routine S YSXT 

The SPM-llM installation procedure consi sts of the f ol 1 owi ng 
steps : 

• Copy RSX-llM V 3.2 kit to basol ine disk (labeled 
"RSXM26") . 

• Perform autopatch to current level. 

• Assign SY: to the "RSXM26" disk. 

• Choose a d i rectory to whi ch you want the SPM-llM kit 
files copied. This will be your SPM-llM kit 
d i rectory . 
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Assuming the SPM-llM directory is [g,m] 
>SET /UIC=[g,m] 
>UFD SY:[g,m] 

>FLX =ddn: [11,2]PM0NCPY.CMD 
XPPMONCPY 

APPLY CORRECTIONS TO EXECUTIVE SOURCES? Y 

• 

APPLY PATCH TO FllACP DISPATCHER MODULE (DISPAT)? Y 
@<EOF> 

>@C200,200]SYSGEN 
>@[200,200]SYSGEN2 

NOTE : If the patch to Fl lACP fails (checksum error) , 
SPM-1 IM will only calculate service times for 
FllACP. If the patch succeeds, SPM-llM will 
generate usage, wait and service times. 

I f PLAS is not generated into the executive, 
create a static common up to 4K word s long with 
VMR to provide space for the COL buffers. 

I f you do not elect to correct the executive 
sources or patch Fl lACP vi a PMONCPY.CMD you can 
do s later v i a the command files: 

1) @PMONSLP for executive source corrections 

2) @PMONPAT for FllACP patch 



When the SYSGEN completes, perform the following 
steps : 

>SET /UIC=[g,m] 

XPPMONBLD 
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NOTE: Be sure to taskbuild COL using the baseline 
library [ 1 , 1 ]S YS L I B . OLB (without ANSI or big 
buffering FCS routi nes) . Otherwise COL will be 
greater than 4096 words and will not be able to 
map its buffers via APR6. 

You can build the MDR or CLF tasks separately 
from PMONBLD.CMD by invoking the command file 
MDRTKB.CMD. 



• You are now ready to run @SMPGEN to generate an MPB 
and run COL. This procedure is described in the next 
secti on . 



3.2 OPERATION 



3.2.1 Generating the Monitor Parameter Block (MPB) 

The MPB is the structure which contains the measurement 
parameters. 

To create an MPB you invoke the command file SMPGEN.CMD. 
See Appendix G for an example SMPGEN. 
The procedure is as follows: 

>SET /UIC=[g,m] 

>@SMPGEN 

where [g,m] is your SPM-llM kit directory. 

The MPB is created in the following way: SMPGEN creates a 
source file (default f i 1 espec is TRACE. PAR), assembles and 
builds the code in the file to produce a binary MPB file 
(default filespec is TRACE. MPB). It is this file which is read 
by the data collection task COL to initialize the measurement 
parameters . 

I n addition to the files mentioned above, SMPGEN a 1 so will 
output, if requested, a saved answer file (default filespec is 
TRACE.CMD). This file can be input to another run of SMPGEN 
and will initialize the symbol table to the values of the 
variables saved in the file. 
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SMPGEN is driven from a menu of parameter categories 
display the menu, type an <ESC>. The menu appears as: 



To 



LEGAL PARAMETER CATEGORIES ARE : 

HOOK TASK MODE 

BUFFER DEVICE SYSTEM 



LABEL 
DONE 



The parameter categories can be specified in any order. I f a 
parameter category is not specified, the parameters will 
receive default values from either: 

• The saved answer file, if one is specified. 

• The table of default parameters. 

Table of Default Parameters 



HOOKS 



all hooks enabled. 



BUFFERS - DYNAMIC region named TRCPAR created in 
partition GEN, 2 buffers with 8 blocks per 
buffer . 

TASKS - All tasks enabled for data collection. 
DEVICES - All devices enabled for data collection. 
MODE - MANUAL mode. 

SYSTEM - System Metrics enabled with 60 second 
sampl i ng i nterval . 



LABEL 



- No 1 abel . 



To select a parameter c ategory , enter the name of the parameter 
category desired as shown in the following example: 

ENTER PARAMETER CATEGORY? HOOK 



Once a parameter category is selected, the detailed parameters 
are specified. Each parameter category has a menu of responses 
which are possible for that parameter category. To get the 
menu, type <ESC>. When you are finished entering parameters, 
type "DONE". 
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A detailed description of each parameter category follows. 
• Label Field 

To select the 1 abel parameter category, type: LABEL 
The following query will be displayed: 
ENTER MPB LABEL? 

The response may be any string from to 63 characters 
long. This user- definable string is stored in the MPB 
and will typically contain notes and comments appli- 
cable to a particular measurement run. It is printed 
as part of the heading on each page of the performance 
report. 

t Hooks 

To select the hooks parameter category, type: HOOK 

The hooks determine which resource usage events are 
recorded to the logfile. 

You do not select each hook individually. Rather, you 
select one or more groups of hooks. Each group of 
hooks contains the subset of hooks which will generate 
a consistent set of data for measuring the usage of a 
particular resource. Hooks may be chosen from the 
following groups: 

- CPU USAGE HOOKS 

This hook group measures task CPU usage. 

It is required for all metrics for task CPU usage. 

- MEMORY USAGE HOOKS 

This hook group measures task memory usage. 

It is required for all metrics for task memory 
usage and % resident time. 

- I/O DEVICE USAGE HOOKS 

This hook group measures task usage of I/O devices 
and the file system. The file system is regarded 
as any ACP which manages a device. Examples are 
FllACP and MTAACP. 



( 
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This hook group is required for all metrics 
relative to task usage of I/O devices or the file 
system. 



Buffers 

To select the buffers parameter category, tvoe- 
BUFFER. y J. J'H 

The hook buffers may be resident in either a static 
common or a dynamic region. The buffer type is 
specified by: 

ENTER BUFFER TYPE? 

The response may be either STATIC i ndicati ng a static 
common or DYNAMIC indicating a dyn ami c region. 

NOTE: If "STATIC" is selected, the COL task must have 
been 1 i nked to a static common in the instal- 
lation phase (see Chapter 3, section 3.1.3). 

If "DYNAMIC" is sel ected, COL must not be linked 
to the static common. 



If the buffer type is DYNAMIC, the name of the 
system-control 1 ed parti ti on in which to create the 
dynamic region is specified by : 

ENTER NAME OF BUFFER MAIN (SYS) PARTITION? 

The name of the buffer common/ reg i on is specified by: 

ENTER NAME OF BUFFER COMMON/REGION? 

The partition will be divided up into a number of hook 
buffers . determined by: 

ENTER NUMBER OF BUFFERS [2.:8.:2.]? 
Note that from 2 to 8 buffers may be specified. 
Finally, the length of each buff^ is specified by: 

ENTER BUFFER SIZE IN 512 B BLOCKS? 

A buffer can be from 1 to 16 blocks long; in other 
words, from 256 words to 4096 words long. 
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If a static common is used for buffering, the total 
space required for buffers must fit into the common . 
If a dynamic region is used, COL will create a region 
large enough to contain the buffers. 



Tasks 

SPM-llM can be set up to collect data for specific 
tasks. For example, there may be some tasks whose 
performance metrics are not desired at all. 
Typi cal ly , system " serv i ce" tasks, such a s FllACP, 
...MCR and QMG — f al 1 into this category. 

To select the task parameter category, type: TASK. 

The following query will appear: 

DO YOU WANT TO TRACE ALL TASKS? 

If your answer is N, you will be given two choices for 
selecting the tasks for data collection: 

Specify the tasks not to trace. 

Specify the tasks to trace. 
The choice is made from the query: 

DO YOU WANT TO SPECIFY THE TASKS NOT TO TRACE? 
If the answer is Y, you are prompted with: 

ENTER NAME OF TASK NOT TO TRACE? 
If the answer is N, you are prompted with: 

ENTER NAME OF TASK TO TRACE? 

You then type, one per line, the names of the tasks 
desired or not desired. Each taskname is from 1 to 6 
characters long. To terminate the list of tasks, type 
<CR>. 

Up to 64 tasknames can be specified. 



Devices 

To get the devices parameter category, type: DEVICE. 
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SPM-llM can be set up to collect data for specific 
classes of devices. If you want to collect data only 
for selected classes of devices, answer N to the 
f ol 1 owi ng query : 

DO YOU WANT TO COLLECT DATA FOR ALL DEVICES? 

A device in RSX-llM may fall into one of four classes 
depending on the bit setting of the "Device Character- 
istics Word" U.CWl in the UCB. 

- Directory Device (DV.DIR) 

- Sequential Device (DV.SQD) 

- Terminal Device (DV.TTY) 
Al 1 Other Devices 

To enable data collection for a device class, a n swer Y 
to the query for that device class. The queries are: 

TRACE DISK (DIRECTORY DEVICE) I/O ACTIVITY? 

TRACE TAPE (SEQUENTIAL DEVICE) I/O ACTIVITY?" 

TRACE TERMINAL I/O ACTIVITY? 

TRACE ALL OTHER DEVICES I/O ACTIVITY? 



Mode 

To select the mode parameter category, type: MODE. 

The performance moni tor can be set up to collect data 
in three different modes. You select the mode by 
answer i ng : 

ENTER MODE? 

The possible modes are: MANUAL, AUTOSTOP and REPEAT. 
Each mode determines the manner in which a measurement 
interval begins and ends. A description of each mode 
f ol 1 ows : 

Manual 

In manual mode, a measurement interval begins when 
the COL task is invoked and ends when the TRM 
(termination) task is run. 
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Autostop 

In autostop mode, a measurement interval begins 
when the COL task is invoked and ends when either 
of the following two events occur: 

A mark-time expires. 

A predetermined number of buffers have been 
filled. 

You determine the type of autostop by responding 
to : 

ENTER SAMPLING TYPE? 
with either TIME or BUFFER. 

If TIME is specified, you then have to specify the 
t imeout i nterval : 

ENTER SAMPLING INTERVAL TIME UNIT [D:MIN] 

ENTER SAMPLING INTERVAL IN units ? 

where "units" is the time unit specified in the 
previous query. Legal units are SEC, MIN or HR. 

NOTE: Do not confuse this sampling interval with 
the system metrics sampling interval 
descri bed in the next section. 



If BUFFER is specified as the interval type, you 
must specify the number of buffers per sample: 

ENTER NUMBER OF BUFFERS PER SAMPLE? 

Note that each buffer is from 1 to 16 disk blocks 
(256 words) long. 

Repeat 

Repeat mode is autostop mode repeated a number of 
times. The sampling interval is specified as for 
autostop mode. In addition, you must specify: 

The number of intervals 

The length of time between intervals. 
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You s pec i f y these parameters by answering the 
following queries: 

ENTER MAX. NUMBER OF SAMPLES? 

ENTER INTERVAL BETWEEN SAMPLES TIME UNIT [D:MTN]? 

ENTER INTERVAL BETWEEN SAMPLES IN units ? 

where "units" is the time unit s pec i f i ed in the 
previous query. 



System 

To select the system-metrics parameter group , type 
"SYSTEM" . 

If you want the system metrics, answer Y the the next 
query: 

DO YOU WANT THE SYSTEM METRICS? [Y/N]: 

I f you answered Y , you must then speci f y the sampl i ng 

interval by : 

ENTER SYSTEM METRICS SAMPLING INTERVAL (SEC) ? 



Done 

When you are finished entering parameters , type 
"DONE". The SMPGEN procedure will then create: 

- A monitor parameter block (MPB) file 
(f il ename.MPB) . 

- A parameter source file ( f i 1 ename . PAR ) . 

A saved answer file { f i 1 ename . CMD , if speci f i ed) . 



Note : SMPGEN will prompt you for the parameter source 
file and saved answer file, and you must enter 
a valid file specification. 
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3.2.2 Using COL 



The COL task is used to initialize the performance monitor, 
start data collection, collect data, stop data collection and 
clean up the performance monitor before exiting. 

Installing COL 

The COL task can be installed in any partition. If possible, 
create a separate 4K word partition for COL . I f installed 1 n a 
system-controlled partition, COL will automatically fix itself 
and mark itself as non- shuf f 1 abl e . It is therefore desirable 
to install and run COL when there is little or no system 
activity in the partition in which COL is installed so as to 
load COL in the lower end of the partition and reduce fragmen- 
tation of the partition. The COL task will occupy approxi- 
mately 4K words of memory. 

COL is t a s k b u i 1 1 with a default priority of 230. Note that COL 
has a higher priority than FllACP and ...MCR, but a lower pri- 
ority than — LDR. It is highly recommended that the priority 
of COL not be altered to a value 1 ower than the def aul t value 
of 230, otherwise excessive overflows may occur which will 
invalidate the measurement runs. 

If full ASCII message text output is desired, install the 
COLMSG task. 

If you are using a static common for COL buffers, be sure to 
install it before installing the COL task. 

Install COL and COLMSG by: 

>INS TRCPAR ;ONLY FOR STATIC COMMON 

>INS COL 
>INS COLMSG 



Running COL 

To run COL, type a command line of the form: 
>COL 1 ogf il e/sw=MPBfil e/sw 

The default logfile specification is SY:[cur u i c]TRAC E . LOG . 
The default MPBfile specification is SY:[cur u i c]TRACE . MPB . 



1 
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stopping COL 

There are two ways to terminate COL: 

• RUN TRM 

• Specify AUTOSTOP or REPEAT mode in SMPGEN. 



RUN TRM will terminate COL regardless of the mode in which COL 
is running: MANUAL, AUTOSTOP or REPEAT. 

COL will also terminate if any of the following abnormal 
conditions are detected: 

• Powerfail recovery 

In this case, if powerfail recovery support is 
included in the executive, COL will issue a SPRA$ 
directive. Upon powerfail recovery, COL will simply 
exi t . 

• Write errors 

If COL detects write errors, it will print a message 
and exit. Write errors will generally corrupt the 
logfile with invalid data. 

Automatic 8-hour termination. 
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COL Switches 



Switch defaults -- 

Output: SY: TRACE. LOG /DENS: 800 /EX: 1 00 . / I F : 1 00 . / W I : 1 . 
Input: SY:TRACE.MPB/BF : 2 : 8 /DL : /D V : LBO /PR : GEN 



Output Switches 


Descri ption 


/AP 


Append records to end of magtape. COL will 
space over all existing files on the magtape 
and append the records for this run starting 
at the current end- of- vol ume point. 


/DENS :density 


Set tape density to 800 or 1600 bpi . 


/ E X : n 


Specifies disk file extent size in 256W 
bl ocks . 


/IF :n 


Specifies disk file initial size in 256W 
bl ocks . 


/WI :n 


Specifies number of retrieval pointers in 
WI ndow block. 


Input Switches 




/BF :m:n 


Number of buffers = m ; size of buffer = n 
256W blocks. 


/DL:n 


Number of MINUTES COL del ays before it 
starts data collection. 


/DV:ddnn 


Device selected for system metrics. 


/PR : parnam 


Partition selected for system metrics. 


/TI :nn 


Collect data only for tasks with TI of TTnn. 
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E xample 1 

>COL DB2: [3,300]CPUTEST/IF:1000/EX: 200=DB1: [5,200]PARM1/DV:DB2: 

logfile is DB2: [3 ,300 ]CPUTEST. LOG with initial size 1000 and 

extent size 200. 

MPB file is DB 1 : [5 , 200]P ARMl . MPB with system metrics specified 
for DB2. 



Example 2 

>COL MM1:/DENS:1600=DB1: [5,200]SAMPLE.MPB 

logfile is on MMl: in 1600 BP! ; MPB file is 
DBl: [5,200]SAMPLE.MPB. 

Example 3 
>COL = 

logfile is SY: [current u i c]TRACE . LOG ; MPB f i 1 e is SY: [current 
uic]TRACE.MPB. 



NOTE: You cannot run COL with a null command line, i.e, >COL 
<CR>. The COL task expects to see explicit filespecs or a 
bare "=" indicating defaults on both input and output. More- 
over, you cannot invoke COL with a command of the form: 

>RUN COL 

since no filespecs can be specified with this form. One final 
thought in this regard : only one copy of COL can be active in 
the system at a time. If mul ti pi e i nvocati ons of COL are 
attempted at different terminals, all but the first will be 
rejected with an error message "MONITORING ACTIVITY IN 
PROGRESS" . 

Once COL is activated, it will run in the mode specified in the 
MPB but al ways for a maximum of 8 hours . Thi s time limit is 
imposed because the KWll-P clock time will overflow in a little 
over 8 hours . 
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COL Messages 

COL outputs two types of messages: error messages and status 
messages . 

Full ASCII error message text will be printed only if the 
COLMSG task is instal 1 ed. If the COLMSG task is not installed, 
COL will print a message of the form "COL ERROR XXXXXX", where 
XXXXXX is the error number. The error messages are listed by 
error number in the following list. Error messages are issued 
if an error condition occurs while COL is starting up and 
initializing the performance monitor. Error messages are 
output to the t e rm i n a 1 of issue (T I : ) for COL . 

Status messages are issued while COL is running in steady 
state. There are status messages for both normal and error 
conditions. Status messages are issued to the console terminal 
(CO:). The COLMSG task does not have to be installed to get 
the status messages; as they are printed directly by the COL 
task . 



COL Error Messages 

000000 COLMSG -- XXXXXX (DSW) GET COMMAND LINE ERROR 

Explanation: A "Get MCR Command Line" directive failure 
occurred . 

User Action: Reenter COL command line using correct 
f rm . 



NOTE: Illegal command forms are: 

1. >COL <CR> 

2. >RUN $COL <CR> 



Legal command line forms are: 

1. >COL filespec/sw = filespec/sw 

2. >COL filespec/sw = /sw 

3. >COL =filespec/sw 

4. >COL = 



1 
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000001 COLMSG -- COMMAND SYNTAX ERROR 

Explanation: Entered incorrect syntax for command line. 
User Action: Reenter command line with correct syntax. 

000002 COLMSG -- MPB FILENAME SYNTAX ERROR 

Expl anati on : Entered i ncorrect syntax for MPB filename. 
User Action: Reenter MPB filename using correct syntax. 

000003 COLMSG -- XXXXXX (PCS) MPB FILE ACCESS FAILURE 

Explanation: COL failed to open MPB file or received a 
read error when attempting to read the MPB file. The 
code XXXXXX (FCS) indicates the FCS error code returned 
to COL. 

User Acti on : Check that speci f i ed MPB file exists, the 
vol ume is mounted (if disk) , or that the file protection 
does not prevent COL from reading the MPB. 

000004 COLMSG -- XXXXXX (DSW) ASSIGN LUN FAILURE 

Expl anati on : COL f a i 1 ed to assign a LUN to the logfile 
device. 

User Acti on : Check that the device specified for 

1 ogf i 1 e is in the system configuration . 

000005 COLMSG ILLEGAL LOGFILE DEVICE TYPE 

Explanation: The device specified for the logfile is 
not of the correct type. Valid logfile device types 
are: Di rectory structured (disk, DECTAPE) , or Sequenti al 
( magtape) . 

User Acti on : Spec i fy a device which is either d i rectory 
structured or sequential. 

000006 COLMSG -- LOG FILENAME SYNTAX ERROR 

Explanation: Entered incorrect syntax for logfile. 

User Action: Reenter logfile specification using 
correct syntax. 

000007 COLMSG -- XXXXXX (FCS) LOGFILE ACCESS FAILURE 

Expl anati on : COL failed to open the logfile. The code 
XXXXXX (FCS) is the FCS error returned to COL. 
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User Acti on : Check that the logfile volume is mounted 
and the necessary directory exi st s (if disk) , or the 
volume is online (if magtape). 

000010 COLMSG -- ILLEGAL BUFFER SPECIFIED 

Explanation: The parameters specified by the /BF:n:m 
switch were not valid. Either the number of buffers (n) 
was out of range (<1 or >8) or the buffer size was out 
of range ( >16 ) . 

User Action: Respecify a valid buffer count or size via 
the /BF switch. 

000011 COLMSG -- XXXXXX (DSW) BUFFER PARTITION NOT IN SYSTEM 

Explanation: The partition specified in the MPB is not 
in the system. 

User Action: If the buffer partition is a static 
common, check that the static common partition exists 
and that the common is installed. 

000012 COLMSG -- BUFFERS WILL NOT FIT INTO PARTITION 

Expl anati on : The number of buffer blocks speci f i ed in 
the MPB (NUMBER OF BUFFERS * BUFFER SIZE IN 512 B 
BLOCKS) is greater than the number of 512 B blocks in 
the physical buffer partition. 

User Action: Do a SMPGEN and specify the NUMBER OF 
BUFFERS and BUFFER SIZE IN 512 B BLOCKS such that the 
product of the two is less than the number of 512 B 
blocks in the physical buffer partition. 

000013 COLMSG -- XXXXXX (DSW) CANNOT CREATE BUFFER PARTITION OR 
ADDRESS WINDOW 

Explanation: COL received a DSW error when attempting 
to create the dynamic buffer partition specified in the 
MPB, r when attempt i ng to create an address window to 
map the dynami c partition. The error XXXXXX (DSW) is' 
the DSW error from the Create Region directive or from 
the Create Address Window directive. 

User Acti on : Check that enough space exists in the GEN 
partition to contain a dynamic region with the size 
specified in the MPB. 

If the error was from a Create Address Window directive, 
check the size of the COL task (look at the map in 
[1 1 , 2]C0L . MAP ) and verify that it is less than or equal 
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to 4096 words. I f COL is greater than 4096 word s , it 
may have been taskbui 1 t using a SYSLIB.OLB with ANS I or 
big buffering FCS routines. COL must then be 
re-taskbuilt using a baseline SYSLIB.OLB which contains 
the non-ANSI FCS routines. 

000014 COLMSG -- MONITORING ACTIVITY IN PROGRESS 

Expl anati on : A multiple invocation of the COL task was 
attempted. Only one copy of COL can be active at a 
t ime . 

User Action: Do not attempt to run more than one copy 
of COL at a time. 

000015 COLMSG -- INVALID MPB FILE 

Explanation: The MPB f i 1 espec speci f i ed in the COL 
command line is not the name of a valid MPB file. 

User Acti on : Reenter a f i 1 espec for a v a 1 id MPB file. 

000016 COLMSG -- INFORMATION RECORD ALLOCATION FAILURE 

Explanation: Insufficient space exists in the buffer 
partition to contain all the Information Records. 

User Acti on : Do a SMPGEN and specify enough blocks 
(NUMBER OF BUFFERS * BUFFER SIZE IN 512 B BLOCKS) to 
contain al 1 the I nf ormati on Record s . The space requ i red 
is roughly that needed to contain the T C B s , PCBs , DCBs , 
and UCBs in the system at the time COL is run. 

000017 COLMSG -- KWll-P VECTOR OR CSR UNAVAILABLE 

Explanation: Either the KWll-P vector is in use, or the 
KWll-P CSR is non-existent on the UNIBUS. 

User Acti on : Check that the correct KW 11 - P vector and 
CSR were speci f i ed in the procedure @PMONBLD.CMD , that 
the vector is not used by another RSX-llM driver or 
task , and that the CSR is addressabl e on the UNIBUS. 

000020 COLMSG -- CANNOT USE SYSTEM'S KWll-P as SPM-llM CLOCK 

Explanation: The RSX-llM system clock is a KWll-P and 
a n attempt was made to use it a s the SPM-llM 
{ performance mon i to r ) clock. 

User Acti on : Check that a separate KWll-P was installed 
for use by the SPM-llM software , and that the vector and 
CSR specified in the procedure @PMONBLD.CMD was for this 
clock. 
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000021 COLMSG -- POOL NODE ALLOCATION FAILURE 

Explanation: COL could not allocate a RSX-llM pool 
node. 

User Action: Re-run COL when sufficient pool is 
available. 

000022 COLMSG -- BUFFER OVERFLOW 

Explanation: COL failed to allocate space for a hook 
record because all buffers were full. 

User Action: Re-run COL, using a larger buffer si ze 
specified either via SMPGEN.CMD or the /BF switch. 

000023 COLMSG --. PARTITION SPECIFIED NOT IN SYSTEM 

Explanation: The partition specified via the /PR switch 
is not configured in the system. 

User Action: Respecify a partition configured in the 
system. 

000024 COLMSG -- ILLEGAL DELAY VALUE SPECIFIED 

Explanation: An illegal delay value has been specified 
via the /DL switch. 

User Action: Re-specify a delay value in the correct 
range (0 to 28800) . 

COL Status Messages 

COL -- PERFORMANCE MONITOR INITIALIZED 

Explanation: COL has successfully initial i zed and is 
now ready to collect data. 

User Action: None 

COL -- PERFORMANCE MONITOR EXITING 

Explanation: COL has stopped data collection and has 
cleaned up its databases. This status message is issued 
by COL immediately prior to exiting. 

User Action: None 
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COL - 



CANNOT MAP OUTPUT BUFFER 



Explanation: COL received an error when attempting to 
map to the output buffer using the Map directive. 

User Action: Check that the dynamic region used as the 
output buffer was successfully created. 

COL -- LOGFILE WRITE ERROR 

Explanation: COL received an PCS or QIO error when 
attempting to write to the logfile. 

User Action: Check the integrity of the logfile. If 
repeated errors occur to the same logfile, rerun COL to 
create a new disk file or mount a fresh tape . 

COL -- LOGFILE CLOSE ERROR 

Explanation: COL received an error when attempting to 
close the logfile. COL will ex i t shortly after printing 
this message with the logfile improperly closed. 

User Act i on : Because the 1 ogf i 1 e was i mp roper 1 y closed, 
it may be difficult to read the logfile and produce a 
performance report. 

COL -- BUFFER OVERFLOW 

Explanation: Hook records were written to the hook 
buffer faster than COL could write them to the logfile. 

User Acti on : I n general , the data collected during a 
measurement i nterval which overf 1 owed is not usabl o by 
the MDR task to produce a performance report . An 
attempt should be made to rerun the measurement to 
obtain data wi thout o verf 1 ow . Prior to attempt i ng 
another measurement run , a SMPGEN should be run wi th 
larger buffers specified than for the measurement run 
which overflowed. 



3.2.3 Using TRM 

The TRM task is used to manually signal the COL task to stop 
data collection, cleanup and exit. TRM will cause COL to exit, 
regardless of the mode in which COL was running: manual, 
autostop or repeat. 

TRM is run by the command >RUN TRM. 
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3.2.4 Using MDR 

MDR is used to read the logfile and produce a performance 
report. MDR is used in conjunction with DRS (sorting) task to 
produce the performance report. The general procedure is as 
follows: 

t >RUN MDR 

MDR>LISTFILE/sw=LOGFILE/sw 

MDR will read the command lino and execute pass 1. 
When pass 1 completes, MDR will print the following 
message and suspend: 

MDR -- YOU MUST NOW SORT THE INTERMEDIATE FILE BY 
USING DRS.TSK 

MDR -- 

>DRS RESOURCE.SRT = RESOURCE.TMP/FO: V: 156/KE : 1. 12/PR:T 

MDR -- AFTER THE SORT HAS COMPLETED, RESUME THIS TASK 
( . . .MDR) 



NOTE: Rather than type the command line to DRS as shown 
above, you can simply invoke the command file (PDRS. 



t >@DRS sorts the intermediate file. 
• >RES MDR 

MDR executes pass 2 and prints the performance report. 



Certain MDR command switches restrict the input data which will 

be processed . I f a logfile contains too much activity for MDR 
1 reduce the data without running out of space, these switches 
{/AF, /BF, /-MD, /NT, /NU, /TS, /UC) may be used to reduce a 
logfile by successive runs of MDR, analyzing only parts of the_^ 
workload in each run. 

When using the switches /NT, /NU, /TS, or /UC, MDR will prompt 
for the task or device names after the command line is 
processed. The tasknames are specified as 1 to 6 RAD50 
characters per entry. Only generic tasknames are used for /NT 
or /TS. The TI device names are entered as "DDnn:", with one 
entry per line. 
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HDR Switches 



Swi tch defaults -- 

output: SY:REDUCE.RPT/SP 

i nput : SY: TRACE.LOG /DM : 2 /LI : 2/RW/SI : 613/MD/SK: 0/DE :800/- IC 



Output Swi tc he s 


Description 


/SP 


/-SP 


SPool output file 


I nput Swi tches 




/AF: 


PChigh:PC1ow 


Only process records from AFter specified 
t ime 


/BF: 


PCh 1 gh : PCI ow 


Only process records from BeFore specified 
time 


/DE: 


n nnn 


Select input magtape DEnsity, 800 or 1600 
(ignored unless /RW is also used) 


/DM: 


n n 


DuMp specified record types: 

01-bufferheaders i 

02 - unknown record types \ 

04 - system configuration info records 

10 - task event hook records 

20 - system metric records 

40 - user information hook records 


/IC 


/-IC 


Replace the % resource column of the report 
with a count of incomplete intervals. 


/LI : 


n n 


Detail level of task workload metrics: 

00 - no report produced 

01 - system-wide summary only 

02 - system and task summaries 

03 - system , task , and T I : summaries 

04 - all summaries and each complete 

task run 

05 - all summaries and all task invocations 






(continued on next page) 
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MDR Switches (continued) 



Input 


Switches 


Do sc ri pt i on 


/MD 




/- 


MD 


Report on tasks with missing data 


/NT 


* 






Do Not process hooks for listed Tasks 


/NU 


* 






Do Not process hooks for listed devices as 
TI : 


/SC 




/- 


SC 


Produce System Configuration section of 
report 


/SI 


n n 






Selects the contents of Sampling Interval 
report by setting nn to the total for the 
desired items: 

UUU ilU iClJUiL jJlUUUut-U 

001 - data collection start/stop times 

nn9 V roil ucann 
UU L. - h \jv\i U S a y t: 

004 - % memory partition usage 

nin — °l Hp \/ IPO "himo Kiic\/ 

020 - % device space used 

UH-U - /o rUUL USGu 

100 - % CKPT space used 

200 - clock time of metrics 

400 - trailing blank line after the metrics 


/SK 


: nnn 




SKip nnn files when opening tape input file 


/RW 




/- 


RW 


Rewind tape input file before opening 


/TS 


* 






Process hook records only for listed TaSks 


/UC 


* 






Process hook records only for listed 
devices as TI: 






* 


-1- ^ 

- U 1 i U 

- the 


oyviU'«ii^::o /ni aiiu /lo aiu liluuuaiijf cAv^iUbiVu* 

switches /NU and /UC are mutually exclusive. 



i 
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MDR Messages 

The MDR messages are issued to the TI device under which MDR 
runs. This section discusses the messages which MDR can issue. 

MDR -- PLEASE ENTER TASKNAMES ONE AT A TIME FOLLOWING EACH 

MDR -- WITH A <CR>. TYPE JUST A <CR> AFTER THE LAST ONE IS 

ENTERED 
MDR -- TSKNAM> 

Explanation: This is the prompt for the generic task- 
names for filtering by the /NT or /IS switch. The last 
line of this message is repeated for each line of input. 

User Action: Enter generic task name(s). 



MDR -- PLEASE ENTER TI DEVICES (DDNN:) ONE AT A TIME FOLLOWING 
EACH 

MDR -- WITH A <CR>. TYPE JUST A <CR> AFTER THE LAST ONE IS 

ENTERED 
MDR -- TI DEVICE> 

Explanation: This is the prompt for device names to be 
used by the /UC or /NU filter. The last line of this 
message is repeated for each line of input. 

User Action: Enter full device name(s) as "DDnn:". 



MDR -- YOU MUST NOW SORT THE INTERMEDIATE FILE BY USING DRS.TSK 
MDR -- (E.G. ) MCR>DRS 

RESOURCE.SRT=RESOURCE.TMP/FO: V: 156/KE : 1. 12/PR: T 
MDR -- AFTER THE SORT HAS COMPLETED, RESUME THIS TASK (TSKNAM) 

Explanation: This message indicates that the first pass 
of MDR has completed. Manual intervention is now 
required to run the DRS task with the given command. ( 
The task name under which MDR is running is given in 
parenthesis in the last lino of the message. 

User Action: Run the DRS task (@DRS.CMD), and when it' 
has completed, resume the MDR task. 



MDR -- DSW:###### F.ERR:###### IOSB:###### ###### PC:###### 

SP:###### 
MDR STK:###### ###### ... 

Explanation: This is a status message which gives 
detail of the internal state of MDR at the time when an 
error is detected. This message is always followed by 

1 



7/81 



GUIDE TO USING SPM-llM 



3-26 



one of the messages discussed below, which describes the 
actualerrorcondition. 

User Action: See action specified for the message 
issued immediately following this status message. 



MDR -- AN INCOMPLETE RESOURCE UTILIZATION REPORT WILL BE 
PRODUCED 

Explanation: An error occurred which prevented the 
completion of pass II of MDR. Although a report will be 
produced, not all task-workload data has been summa- 
rized. A previous error message is issued giving the 
cause of this condition. 

User Action: As specified for previous message. 



MDR -- ATTEMPT TO PRINT NULL TWB 

Explanation: An internal inconsistency occurred in the 
pass II processing of MDR. 

User Action: * * * SPR ! 

MDR -- ATTEMPTING TO DEALLOCATE TWB NOT IN TSKHD 

Explanation: An internal inconsistency occurred in the 
pass I processing of MDR. 

User Action: * * * sPR ! 



MDR -- CHECKPOINT USAGE > 100% 

Explanation: A Checkpoint metric indicates more than 
100% usage of the checkpoint space. The metric is not 
reported . 

User Action: Ensure logfile is not corrupted. 



MDR -- CLOCK STOPPED OR HOOK RECORD OUT OF TIME SEQUENCE. 

Explanation: The records in the logfile do not follow a 
strict time sequence. This condition invalidates the 
data in the logfile. 

User Action: Ensure that the KWll-P clock is 
functioning. Re-collect the data. 



1 
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MDR -- COMMAND READ ERROR 

Explanation: An I/O error occurred while attempting to 

read the MDR command line. 

User Action: Reenter the MDR command. 



MDR COMMAND SYNTAX ERROR 

Explanation: The command as entered has improper 
syntax. 

User Action: Reenter the corrected MDR command. 



MDR -- COMPLETION ERROR IN INPUT READ 

Explanation: An I/O error occurred while reading the f 
logfile. This condition will be treated as end-of-file 
and MDR will attempt to continue. This may be 
symptomatic of a corrupted logfile. 

User Action: Check lOSB for error cause. Rerun MDR 
using another logfile if necessary. 



MDR CONFLICTING SWITCHES /TS+/NT OR /UC+/NU 

Explanation: The switches /TS and /NT were both speci- 
fied, or the switches /UC and /NU were both specified. 
Only one of each pair of switches may be specified. 

User Action: Reenter the command line without both of 
the conflicting switches. 



MDR -- DEVICE USAGE > 100% 

Explanation: MDR processed a system metric record which 
1 ndicates greater than 100 percent of device uti 1 i- 
zation. No graphic output will be produced for the' 
suspect record. 

User Action: * * * spr i 



MDR -- DEVICE'S ACP NOT FOUND 

Explanation: The system information records indicated 
that a device was mounted, yet no TCB for the ACP task 
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was found. The device may 

rently with COL ' s scan of 
generic ACP name will be 
f uncti ons . 

User Action: None. 



have been dismounted concur- 
the system configuration. A 
used for the device's ACP 



MDR -- DYNAMIC SPACE ALLOCATION FAILURE 

Explanation: MDR was unable to sufficiently extend 
itself to provide space for initialization of pass I. 
This indicates a severe shortage of necessary dynamic 
space. 

User Action: Ensure MDR is checkpointable. Ensure the 
partition where MDR runs has enough space for MDR to 
extend. Use SET /MAXEXT to allow sufficient extension. 
Use of smaller buffers by COL will lower the MDR space 
requirement. 



MDR -- ERROR ATTACHING, POSITIONING OR SELECTING DENSITY OF 
MAGTAPE 

Explanation: An I/O error occurred when attempting to 
open the logfile on magtape. The drive may have been 
/ mounted to MTAACP which is incorrect since MDR does QIOs 

directly to the tape device driver. 

User Action: Correct the condition and rerun MDR. 



MDR -- ERROR CLOSING INPUT FILE 

Explanation: An I/O error occurred when closing the 
i nput 1 ogf i 1 e . 

User Action: None. 



MDR -- ERROR CLOSING REPORT FILE 

Explanation: An I/O error occurred when closing the 

report file. This file will not be properly closed or 
spool ed . 

User Action: Correct the condition and manually close 

the file, or rerun MDR . 
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MDR -- ERROR CLOSING RESOURCE. TMP FILE 

Explanation: An I/O error occurred at the end of pass I 

when closing the RESOURCE. TMP file. The DRS task will 

not be able to read this file until it is properly 
closed. 

User Action: Correct the condition and manually close 

the file, or rerun MDR. 



MDR -- ERROR DELETING RESOURCE. TMP FILE 

Explanation: An I / error occurred when MDR deleted 
its temporary file. The file is not properly closed, or 
deleted. 

User Action: Manually unlock and delete this file. 

( 

MDR -- ERROR IN GTSK$S 

Expl anati on : The directive f a i 1 ed preventing MDR from 
obtaining its taskname. The message requesting the sort 
to be run will not include MDR ' s taskname. 

User Act i on : None . 



MDR -- ERROR IN INPUT READ QIO 

Expl anati on: An I/O error occurred while reading the 
logfile. This condition will be treated as end-of-file 
and MDR will attempt to continue. This may be 
symptomatic of a corrupted logfile. 

User Action: Check DSW for error cause. Rerun MDR 
using another logfile if necessary. 

MDR -- ERROR OPENING RESOURCE. SRT FILE 

Explanation: An error was reported by FCS when MDR 
attempted to open the RESOURCE . SRT file for pass 1 1 . 
Pass II will not be able to run. 

User Action: Correct the condition indicated by F.ERR 
and rerun MDR. 
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MDR -- ERROR OPENING RESOURCE. TMP FILE 

Explanation: An error was reported by PCS when MDR 
attempted to open the RESOURCE. TMP file for write in 
pass I. Pass I will not be able to run. 

User Action: Correct the condition indicated by F.ERR 
and rerun MDR. 



MDR -- ERROR OUTPUTTING PRINT LINE 

Explanation: An error was reported by PCS when MDR 
attempted to output a record to the report file. MDR 
will attempt to continue to produce the report. If this 
error is not caused by a transient condition the message 
will be repeated, and MDR will have to be aborted. 

User Action: Correct the condition and rerun MDR. 



MDR -- ERROR READING MPB 

Explanation: An I/O error occurred when attempting to 
read the first block of the logfile. 

User Action: Correct the condition and rerun MDR. 

( 

MDR -- ERROR READING RESOURCE. SRT FILE 

Explanation: An I/O error occurred in pass II when 
attempting to read from the RESOURCE. SRT file. This 
will be treated as an end-of-file condition. 

User Action: Correct the condition and rerun MDR. 



MDR -- ERROR REOPENING RESOURCE. TMP PILE 

Explanation: An I/O error occurred when attempting to 
re-open the RESOURCE. TMP file so it could be deleted. 
The RESOURCE. TMP file will not be deleted. 

User Action: Delete the file manually. 



MDR -- ERROR SKIPPING OVER MPB BUFFER 

Explanation: An I/O error occurred when repositioning 
the tape logfile so the MPB could be reread once the 
buffer size is known . 
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User Action: Correct the condition and rerun MDR. 

MDR ERROR WRITING RESOURCE. TMP FILE 

Explanation: An I/O error was reported by PCS for a 
write operation during pass I. 

User Action: Correct the condition and rerun MDR. 



MDR -- EXPECTED RIB NOT FOUND 

Explanation: An inconsistency occurred in MDR's 
internal dynamic data structures. 

User Action: See Chapter 7, Section 7.3. 

MDR -- EXPECTED RWB PREDECESSOR NOT FOUND IN OVERLAP 

Explanation: An inconsistency occurred in MDR's 
internal dynamic data structures. 

User Action: * * * SPR ! 



MDR -- EXPECTED RWB PREDECESSOR NOT FOUND IN MERGE 

Explanation: An inconsistency occurred in MDR's 
internal dynamic data structures. 

User Action: * * * sPR ! 

MDR IDLE TIME > lOOX 

Explanation: MDR processed a system metric record which 
indicates greater than 100 percent of CPU idle time. No 
graphic output will be produced for the suspect record. 

User Action: See Chapter 7, Section 7.5. 

MDR IMPROPER FORMAT OR NO SUCH DEVICE IN SYSTEM. PLEASE 
RETYPE. 

Explanation: An improper response was entered to the 
prompt for TI filter devices. 

User Action: Enter a corrected response. 
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MDR -- INPUT FILESPEC OR SWITCH SYNTAX ERROR 

Explanation: An improper command line was used with 
MDR. 

User Action: Reenter the command. 



MDR -- INVALID DENSITY SELECTED, 800 OR 1600 ONLY 

Explanation: A magtape density other than 800 or 1600 
was specified. 

User Action: Reenter the command with the correct 
densi ty . 



MDR -- INVALID DEVICE SPACE METRIC RECORDED 

Explanation: A system metric record indicates more than 
100% of device space used. The device space metric will 
not be reported. This metric is only available for 
devices mounted to FllACP. 

User Action: Ensure logfile not corrupted. 



MDR -- INVALID INPUT DEVICE TYPE 

Explanation: An attempt was made to reduce a logfile 
which is not on either a disk or tape volume. MDR can 
only use disk or tape for the input file. 

User Action: Do not use MDR to read logfiles not 
residingondiskortape. 



MDR -- INVALID INPUT FILESPEC 

Explanation: A syntax error occurred in the input 
filespec part of the MDR command. 

User Action: Correct and reenter the command. 



MDR -- INVALID LISTING LEVEL 

Explanation: An invalid listing level was specified in 
the /LI switch. Acceptable values range from to 5. 

User Action: Correct and reenter the command. 
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MDR - 



- INVALID MPB FOUND BY ALC 



Explanation: The logfile was found to contain improper 
data. This may be a result of using MDR to read a 
logfile produced by an i ncompatabl e COL version. This 
may also be the result of using MDR to read a file which 
was not produced by COL, or was corrupted. 

User Action: Rerun MDR using a valid logfile. 



MDR -~ INVALID MPB FOUND BY INF 

Explanation: The MPB did not pass validity testing when 
it was reread once the logfile buffer size was known. 
The logfile may have been corrupted while MDR was 
process! ng it . 

User Action: * * * SPR ! [ 



MDR -- INVALID POOL METRIC RECORDED 

Explanation: A Pool metric indicates more than 100% DSR 
usage. The metric is not reported. 

User Acti on : Ensure logfile is not corrupted . Do not 
change DSR size while COL is running. 



MDR -- INVALID RAD50 CHARACTER IN YOUR INPUT. PLEASE RETYPE. 

Explanation: The response to the taskname prompt for 
filtered names was not a valid RSX-llM taskname. All 
letters should be in uppercase. 

User Action: Correct and retype the response. 



MDR -- INVALID TIME VALUES; /AF MUST BE EARLIER THAN /BF 

Explanation: An attempt to use time filter values which 
overlapped causes this message. This condition will not 
allow any records to pass the filter for processing. 

User Action: Correct and reenter the MDR command. 
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MDR -- MEMORY USAGE > 100% 

Explanation: MDR processed a system metric record which 
indicates greater than 100 percent of partition utili- 
zation. No graphic output will bo produced for the 
suspect record. 

User Acti on : * * * SPR ! 



MDR -- MISSING INFO FOR DEVICE METRIC 

Explanation: The Info record describing the system 
metric device was not found. Device system metrics will 
not be reported. 

User Action: Do not load or unload device drivers while 
COL is active. Ensure logfile is not corrupted. 



MDR MISSING I$SYS FOR POOL METRIC 

Explanation: The DSR size was not found in the logfile. 
The Pool system metric is suppressed. 

User Action: Ensure logfile is not corrupted. 

f' 

MDR -- MISSING "=" AND INPUT FILESPEC 

Explanation: The input command contains no "=" and no 
input filespec. Both input and output filespocs must be 
supplied or defaulted. 

User Action: Enter a corrected MDR command including 
the "=". 

( 

MDR -- MORE THAN ONE INPUT FILESPEC NOT ALLOWED 

Explanation: The MDR command contains more than one ^ 
input filespec. 

User Action: Enter a corrected MDR command with only 
one input filespec. 



MDR -- MORE THAN ONE OUTPUT FILESPEC NOT ALLOWED 

Explanation: The MDR command contains more than one 
output f i 1 espec . 
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User Action: Enter a corrected MDR command with only 
one output f i 1 espec . 

MDR -- MPB FOUND AT LOCATION OTHER THAN FIRST RECORD OF FILE 

Explanation: An MPB was read in the wrong position in 
the logfile. This is indicative of a corrupted logfilo. 
MDR will bypass this MPB and attempt to continue to 
process the corrupted logfile. Reports produced from 
this logfile are suspect. 

User Action: Use a different logfile for analysis. 



MDR -- MPB NOT FOUND - NOT TRACE FILE 

Explanation: The MDR input file did not begin with a 

MPB. Either the file was corrupted or it is not a f 

logfile. 

User Action: Use a different logfile for analysis. 



MDR -- NO FOLLOWING PRIMARY RWB FOUND 

Explanation: An internal i nconsi stency was detected in 
pass I . 

User Action: ***SPR! 



MDR -- NO FPP OR BUILT /-FP 

Expl anati on : MDR is unable to initialize for FPP ASTs . 
Either MDR was ta s kb u i 1 1 with the /-FP switch, or the 
processor where MDR is running has no FPP. This message 
cannot occur if the EIS version of MDR is used. ( 

User Action: Rebuild MDR using the distributed .CMD 
file. Only run the FPP version of MDR on processors 
with an FP-11. 



MDR -- OUTPUT F ILESPEC OR SWITCH SYNTAX ERROR 

Explanation: A syntax error was detected in the output 
filespec or an invalid output switch was specified. 

User Action: Correct and reenter the MDR command. 
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OVERFLOW BEFORE MPB - BAD TRACE FILE 



Explanation: The logfile indicates buffer overflow 
occurred before the MPB was written. Either the logfile 
was corrupted, or the file was not produced by COL. 

User Action: Use another file for MDR input. 



OVERFLOW IN FIRST PASS SUMMARIZATION 

Explanation: A floating overflow occurred in pass I. 
Incorrect data will be reported for the particular task 
and summaries which this data represents. 

User Action: Use the resulting report with caution. 
Use filtering to limit the amount of data processed to 
prevent thi s condition. 



OVERFLOW IN SECOND PASS SUMMARIZATION 

Explanation: A floating overflow occurred in pass II, 
Incorrect data will be reported for the particular task 
and summaries which this data represents. 

User Action: Use the resulting report with caution. 
Use filtering to limit the amount of data processed to 
prevent this condition. 



PARTITION RIB NOT FOUND FOR S$MEM 

Explanation: A system metric record was read for a 
partition which was not described by the system con- 
figuration information records. The graphic output of 
memory utilization will be suppressed. 

User Action: None. 



PRINT LINE TOO LONG 

Explanation: MDR generated a report file record longer 
than 132 bytes. The line is truncated by the logic 
which writes to the file. 

User Action : * * * SPR ! 
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MDR - 



- RIB LIST LINKAGE ERROR 



Explanation: An inconsistency was detected in MDR ' s 
internal representation of the system configuration. 

User Action: * * * SPR ! 



MDR -- RWB WITHOUT TWB FOUND IN RESOURCE. TMP 

Explanation: A record in the RESOURCE. SRT file was 
encountered in an illogical position. The record is 
d i sg arded . 

User Action: ***SPR! 



MDR -- SUMMARIZING FROM NULL TWB 

r 

Explanation: An inconsistency was detected in the pass 
1 1 data structures . 

User Action: * * * SPR ! 



MDR -- SUMMARIZING INTO NULL TWB 

Explanation: An inconsistency was detected in the pass 
II data structures . 

User Action: * * * SPR ! 



MDR -- SVTK FAILURE 

Explanation: The RSX executive rej ected MDR ' s attempt 
to specify an SST vector. 

User Acti on : Correct the condition indicated by the DSW 
and rerun MDR. 



MDR -- SYSTEM + IDLE TIME > 100% 

Explanation: A system metric record was read which 
indicates the total of kernel and idle time is greater 
than the elapsed time. The graphic output for the 
record is suppressed. 

User Action: See Chapter 7, Section 7.5. 
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MDR - 



- SYSTEM TIME > 100% 



Explanation: A system metric record was read which 
indicates more kernel time than elapsed time. The 
graphic output for the record is suppressed. 

User Action: See Chapter 7, Section 7.5. 



MDR -- TI : READ ERROR 

Explanation: An I/O error occurred when reading filter 
values from the user . 

User Acti on : Rerun MDR . 



MDR -- TRAP ### 

Explanation: A floating point or conversion error 
occurred. The octal number in this message indicates 
the precise error cause. 

User Action : * * * SPR ! 



MDR -- TRUNCATED INPUT FILE RECORD 

Explanation: The end of a buffer was reached before all 
the records in that buffer were processed. This 
indicates a corrupted logfile. 

User Action: Use a different logfile for analysis. 



MDR -- TWB/RWB/RIB DYNAMIC SPACE ALLOCATION FAILURE 

Explanation: MDR was unable to get needed virtual space 
for a dynamic structure in pass I. However sufficent 
dynamic storage was obtained to begin pass I. 

User Action: Ensure MDR is checkpointable. Ensure the 
partition where MDR runs has enough space for MDR to 
extend. Use SET /MAXEXT to allow sufficient extension. 
Use of smaller buffers by COL will lower the MDR space 
requirement. Use of filtering of MDR input will also 
lower this space requirement. Use overlaid MDR. 
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MDR -- UNABLE TO ALLOCATE RESOURCE. SRT BUFFER 

Explanation: MDR was unable to get needed virtual space 
for a dynamic structure in pass II. 

User Action: Ensure MDR is checkpointable. Ensure the 
partition where MDR runs has enough space for MDR to 
extend. Use SET /MAXEXT to allow sufficient extension. 
Use of filtering of MDR input will lower this space 
requirement. Use overlaid MDR. 



MDR -- UNABLE TO ALLOCATE RIB 

Explanation: MDR was unable to sufficiently extend 
itself to provide space for initialization of pass I. 
This indicates a severe shortage of necessary dynamic 
space. 

r 

User Action: Ensure MDR is checkpointable. Ensure the 
partition where MDR runs has enough space for MDR to 
extend. Use SET /MAXEXT to allow sufficient extension. 
Use of smaller buffers by COL will lower the MDR space 
rcqu i rement . 



MDR -- UNABLE TO OPEN INPUT FILE 

Explanation: An I/O error occurred when MDR attempted 
to open the 1 ogf i 1 e . 

User Action: Correct the condition and rerun MDR. 



MDR -- UNABLE TO OPEN OUTPUT FILE 

Explanation: An I/O error occurred when MDR attempted 
to open the report file. 

User Action: Correct the condition indicated by F.ERR 
and rerun MDR. 



MDR -- UNKNOWN INFO TYPE RECORD FOUND 

Explanation: A corrupted logfile, or a file not 
produced by COL is being used as MDR input. 

User Action: Use a different file for MDR input. 



i 
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MDR -- UNKNOWN RECORD TYPE 

Explanation: A corrupted logfile, or a file not 
produced by COL is being used as MDR input. 

User Action: Use a different file for MDR input. 

MDR -- VALIDATION ERROR 

Explanation: MDR is being used to process a logfile 
after the service period has expired. 

User Action: Contact your local Digital office to 
extend the service period. 

MDR -- WILDCARD NOT ALLOWED IN FILESPEC 

Explanation: The MDR command contains a wildcard. 

User Action: Reenter the command without any wildcards. 

MDR -- WRONG FOLLOWING PRIMARY RWB FOUND 

Explanation: An inconsistency was detected in MDR ' s 
pass I dynamic data. 

User Action: ***SPR! 
3.2.5 Using CLF 

CLF is used to copy logfiles produced by COL. The three modes 
of CLF operation are: 

t Buffer Transfer Mode, 

which copies a logfile from either disk or tape, to 
disk or tape, maintaining the logfile format which MD"R 
uses for i nput . 

• FCS Record Transfer Mode, 

which copies a logfile from either disk or tape, 
producing an output file with variable length FCS 
records. 
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• Read-only Mode, 

which reads the logfile, computes overflow and buffer 
counts, but does not create a new file. 

The general procedure for using CLF is: 

>RUN CLF 

CLF> [OUTFILE/sw =] LOGFILE/sw 

Note that the output filespec and "=" are optional. If these 
are not specified, CLF will operate in read-only mode, 
producing no output file. 

When FCS mode is specified (by the /FCS switch), the records 
have the format specified in appendices A through D . The first 
word of each record is the record ID which uniquely identifies 
the record type. If overflows occur within the data stream, a 
special " overf 1 ow r ec o rd " is pi aced in the output file a t the 
point where records were lost due to overflow. The format of 
this (length = 4. bytes) record is: 




600(8) = overflow record ID 



count of records lost by overflow at 
this point 



When the /FCS switch is used, the default output filespec is 
changed to TRACE . FCS . 

After CLF has completed reading the input file, the run 
statistics will be reported to CLE's TI:. 
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CLF Switches 

Switch defaults -- 

output: SY:TRACE.L0G/-AP/DE:800/-FCS 
i nput : SY:TRACE.LOG/DE :800/RW/SK:0 



Output Switches 


Descri ption 


/AP /-AP 

/DE : nnnn 
/PCS /-PCS 


APpend file to the end of magtape. CLF 
will space over all existing files on the 
magtape and write the new file starting at 
the current e nd- of- vol ume point. 

Selects output magtape DEnsity, 800 or 1600 

Selects FCS formatted output file 


Input Switches 




/ D E : n n n n 

/RW /-RW 
/SK: nnn 


Selects input magtape DEnsity, 800 or 1600 
(ignored unless /RW is also used) 

Rewind tape input file before opening 

SKip nnn files when opening tape input file 



CLF Messages 

The CLF messages are issued to the TI device under which CLF is 
run. This section discusses the messages which CLF can issue. 

CLF -- #### BUFFERS READ 

CLF -- #### RECORDS READ 

CLF -- #### BUFFERS WITH OVERFLOW 

CLF -- #### RECORDS LOST BY OVERFLOW 

Explanation: This statistics message is output at the 
completion of each run of CLF, indicating the statistics 
about the input file. 

User Action: None. 
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CLF -- DSW:###### F.ERR:###### IOSB:###### ###### PC:###### 

CLF STK:###### ###### ... f 

Explanation: This is a status message which gives 
detail of the internal state of CLF at the time when an 
error is detected . This message is always f ol 1 owed by 
one of the messages discussed below, which describes the 
actual error condition. 

User Action: See action specified for the message 
issued immediately after this status message. 



CLF -- COMMAND READ ERROR 

Explanation: An I/O error occurred while reading the 
command 1 i ne . 

User Action: Reenter the command. 



CLF COMMAND SYNTAX ERROR 

Explanation: The command has improper syntax. 
User Action: Reenter the corrected command. 



CLF -- COMPLETION ERROR IN INPUT READ 

Ex pi anat i on : an I/O error occurred while reading the 
input file. This condition, which may be symptomat i c of 
a corrupted logfile, will be treated as end-of-file. 

User Action: Check F.ERR and lOSB for error cause, or 
use another logfile. 

\ 

CLF -- ERROR ASSIGNING INPUT DEVICE 

Explanation: CLF was unable to assign a LUN to tht5 
input file. 

User Act i on : Check DSW and F.ERR for cause. Ensure the 
filespec syntax is correct. 



CLF -- ERROR ASSIGNING OUTPUT DEVICE 

Explanation: CLF was unable to assign a LUN to the 
output file. 
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User Action: Check DSW and F.ERR for cause. Ensure the 
filespec syntax is correct. 



CLF -- ERROR ATTACHING, POSITIONING OR SELECTING DENSITY OF 
MAGTAPE 

Explanation: An I/O error occurred when attempting to 
open a file on magtape. 

User Action: Ensure the drive is not mounted if logfile 
format is used for that file. Ensure the output drive 
is selectable, and not write locked. Correct the error 
indicated by DSW or lOSB. 



CLF -- ERROR CLOSING INPUT FILE 

Explanation; An I/O error occurred when closing the 
input file. 

User Action: None. 



CLF -- ERROR CLOSING OUTPUT FILE 

Explanation: An I/O error occurred when truncating or 
closing the output file. 

User Action: Correct the condition and rerun CLF, or 
manually unlock the output file. 



CLF -- ERROR IN INPUT READ QIO 



Explanation: An I/O error 
input file. This condition, 
a corrupted logfile, will be 

User Action: Check DSW for 
logfile if necessary. 



occurred while reading the 
which may be symptomatic of 
treated as end-of-file. 

cause. Rerun using another 



CLF -- ERROR READING MPB 

Explanation: An I/O error occurred when reading the 
first block of the logfile. 

User Action: Correct the condition and rerun. 
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CLF -- ERROR WRITING TO OUTPUT FILE 

Explanation: An I/O error occurred when writing to the ( 
output file. 

User Action: Correct the condition and rerun. 



CLF -- INPUT FILESPEC OR SWITCH SYNTAX ERROR 

Explanation: A syntax error was detected in the input 
f i 1 es pec . 

User Action: Reenter the corrected command. 



CLF -- INVALID DENSITY SELECTED, 800 OR 1600 ONLY 

Explanation: A magtape density other than 800 or 1600 
wa s spec i f i ed . 

User Action: Reenter the command with a correct 
density. 



CLF -- INVALID INPUT DEVICE TYPE 

Explanation: An attempt wa s made to read a file not on 
disk or tape. Disk and tape are the only acceptable 
media for logfiles. 

User Action: Do not use CLF to read files not on disk 
or tape . 



CLF -- INVALID MPB FOUND 

Expl anati on: The first block of the input file does not 
pass certain v a 1 i d i t y tests which ensure the file is a 
logfile. This may be caused by a corrupted or obsolete 
1 g f i 1 e . 

User Action: Use a different logfile. 



CLF -- INVALID OUTPUT DEVICE TYPE 

Explanation: An attempt was made to write in logfile 
format to a device other than disk or tape. 

User Action: Only write logfile format to d.isk or tape. 
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CLF - 



- MORE THAN ONE 
Ex pi anat i on : 
User Action: 



INPUT FILESPEC NOT ALLOWED 

The command has improper syntax. 

Reenter the corrected command. 



CLF -- MORE THAN ONE OUTPUT FILESPEC NOT ALLOWED 

Explanation: The command has improper syntax. 
User Action: Reenter the corrected command. 



CLF -- MPB NOT FOUND - NOT TRACE FILE 

Explanation: The first block of the input file does not 
pass certain validity tests which ensure the file is a 
logfile. This may be caused by a corrupted or obsolete 
1 g f i 1 e . 

User Action: Use a different logfile. 



CLF -- OUTPUT FILESPEC OR SWITCH SYNTAX ERROR 

Explanation: A syntax error was detected in the input 
f i 1 e s p e c . 

User Action: Reenter the corrected command. 



CLF -- OVERFLOW BEFORE MPB - BAD TRACE FILE 

Explanation: The first block of the input file does not 
pass certain validity tests which ensure the file is a 
logfile. This may be caused by a corrupted or obsolete 
logfile. 

User Action: Use a different logfile. 



CLF -- TRUNCATED INPUT FILE RECORD 

Explanation: The end of a buffer was reached before all 
e. records in that buffer were processed. This indicates a 

corrupted 1 ogf i 1 e. 

User Action: Use a different logfile. 



i 
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CLF UNABLE TO OPEN INPUT FILE 

Explanation: An I/O error occurred while opening the 
input file. 

User Action: Correct the condition and rerun. 

CLF -- UNABLE TO OPEN OUTPUT FILE 

Explanation: An I/O error occurred while opening the 
output file. 

User Action: Correct the condition and rerun. 



CLF -- UNKNOWN RECORD TYPE 

Explanation: An unknown record ID was found in the 
file. 

User Acti on : Use a different 1 o g f i 1 e . 

CLF -- WILDCARD NOT ALLOWED IN FILESPEC 

Explanation: A wildcard was found in the command. 

User Action: Reenter the command without wildcards. 



3.2.6 Writing User Information to the Logfile 

The QPDRV driver provides a way for a user task to write user 
i nf ormati on to the same logfile that COL currently has open . A 
task does this by issuing a Q 1 to QP : , with up to six words 
of user information specified in the QIO parameter words. 

The QPDRV driver is similar to the null driver NLDR V . 1 1 is an 
infinite sink for writes and an infinite source of EOFs for, 
reads . QPDRV is compati bl e with FCS and RMS QIO functions. 
Al 1 of the following Q 1 functions are defined a s legal and 
control for QPDRV: lO.KIL, lO.RLB, lO.WlB, 10. ATT, lO.DET, 
lO.FNA, lO.ACR, lO.ACW, 10. ACE, lO.DAC, lO.RVB and lO.WVB. 

QPDRV contains a hook point defined as H$USER. When a QIO is 
issued to QP:, a hook record with hook ID H$USER is written. 
The H$USER record cont a i n s the six Q 1 parameter word s speci- 
fied by the user. Sec Appendix A for a complete specification 
of the hook record. 
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To use QPDRV, you must load it by the command: 
>LOA QP: 

QPDRV is built via the command file PMONBLD.CMD. The image and 
symbol table files for QPDRV are contained in [1,54]. 

Exampl e : 

ALUN$C 1,QP,0 

QIOW$C I0.WLB,1,1, <100 , 200, 300 , 400 , 500 , 600> 

will result in a H$USER record with the QIO parameters 100, 
200, 300, 400, 500 and 600 written to the logfile. 

To dump a stream of H$USER records in the performance report, 
you run MDR and use the /DM:40 switch. If you only want the 
H$USER records printed, the suggested command syntax is: 

MDR> output=input/DM:40/LI :0/SI :0 

Usage note: If you enable device type "OTHER" in SMPGEN, then 
for each QIO to QP:, three hook records are written: H$QDRV, 
H$I0DN and H$USER. However, if you disable device type "OTHER" 
in SMPGEN, then for each QIO to QP: only the H$USER hook record 
is wr i tten . 



7/81 



GUIDE TO USING SPM-llM 



3-49 



f 



( 



i 



Chapter 4 
DATA COLLECTION AND 

REDUCTION PROCEDURES 



COL and MDR are complementary tools which can be used to 
collect large amounts of performance data and interpret the 
data to a great degree of precision. Both COL and MDR have_a 
number of parameters and switches which provide flexibility in 
both collecting and interpreting the data. In the following 
sections we describe how to utilize the parameters of COL and 
MDR to collect the best possible set of data to analyze your 
computer system. 

4.1 DATA COLLECTION PROCEDURE 

There are a number of questions you should answer before 
running COL to collect data: 

• Length and type of measurement interval? 

• Resource types enabled for data collection? 

• Device classes enabled for data collection? 

• Tasks enabled for data collection? 

• System metrics enabled? 



4.1.1 Measurement Period 

The measurement period is defined as the time during which COL 
is collecting data. Typically this time is one continuous time 
interval; however, it may consist of a number of time intervals 
piecewise added together. 



( 
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Under most conditions, you should select a continuous measure- 
ment period. This is done by running COL either in MANUAL mode 
or AUTOSTOP mode. 

MANUAL mode should be used when: 

• There is an operator available to terminate COL. 

9 You estimate the logfile space available is sufficient 
to contain all the data collected for the measurement 
peri od . 



AUTOSTOP mode should be used when: 

• An operator is not available to terminate COL. 

• You want to run COL for a fixed amount of time 
(AUTOSTOP on TIME) . 

You want to set a limit on the amount of logfile space 
used (AUTOSTOP on BUFFER) . 



Under some conditions, particularly if the system is under 
heavy activity for long periods of time, COL wi 1 1 collect too 
much data given the available logfile space. To reduce the 
logfile space used, you can run COL in REPEAT mode. However, 
you shoul d do so carefully. The chief concern when runni ng COL 
in REPEAT mode is that "incomplete intervals" may result if a 
task or operation is outstanding exactly when COL starts or 
stops data collection. For example, if you start COL precisely 
when a task is active and has an I/O operation queued to the 
disk, an incomplete interval will be flagged by MDR for both 
the task invocation and for the I/O operation. This condition 
does not invalidate other information in the performance 
report, it just "leaves out" some information which potentially 
may be valuable. You can minimize the number of incomplete 
i nterval s by minimizing the number of times COL enabl es or 
disables data col 1 ection for a measurement peri od . 

Let's say you want to col 1 ect data during a normal 8-hour 
daytime shift and you have only one 2400 foot magtape avai 1 abl e 
for the logfile. However , you estimate that if COL runs al 1 
day, about two 2400 foot tapes will be needed. What you need 
to do is cut the amount of data collected in half. Consider 
the following alternative measurement schemes: 

• oaill p I e U I III e = l lll l ii u u c ^ i i iiic D e u mc c ii a am p i c a - 

1 minute. 
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• Sample time = 30 minutes; Time between samples = 
30minutes. 

® Sample time = 2 hours; Time between samples = 
2 hours. 



Scheme 1 will usually r e s u 1 t in the highest number of 
incompletes, yet it probably will not "miss" any important 
system activity. Scheme 3 will probably result in the lowest 
number of incompletes, yet it is vulnerable to missing 
important intervals of system activity. Scheme 2 will probably 
result in a low number of incompletes, yet it has a good chance 
of capturing all periods of important system activity. 

What we're observing here is an old problem in communications 
systems : How fast do you sample a signal to be able to 
reconstruct the signal from the sampled data? In our case, the 
problem is: how fast do you sample the workload in order to 
reconstruct it? 

In communication systems, you sample the signal at twice the 
highest frequency in the signal. In computer systems, it vsould 
be reasonable to sample the workload at twice the highest 
frequency of variation in the workload. Thus if you observe 
the workl oad to fluctuate up and down about four times per day , 
then 8 samples per day (every 30 minutes) would reduce the 
amount of data and yet collect sufficient data to reconstruct 
the workload. 



4.1.2 Resource Types 

No rmal 1 y you want to collect data for al 1 resource types (CPU, 
memory, I/O). If the amount of data collected is too large, 
you can select one resource type per measurement period and run 
a number of measurement periods. 

The hooks are grouped according to resource type. To select a 
particular resource type, you select the corresponding hook 
group . 



4.1.3 Device Classes 

The device classes arc: Di rectory , Sequential , Termi nal , and 
Other. If you want to measure the resource contention for a 
device, select it for data collection. Normally the disks are 
shared devices and should be selected. If the line printer is 
spooled and attached to the despooler task you may not need to 
collect usage data for it. Similarly, terminals are normally 
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singly used by one task at a time; the measurement results may 
not be useful from a resource contention point of view. 

4.1.4 Tasks 

The tasks selected for data collection are the definition of 
the workload that you want to measure. For example, if you 
want to analyze the application workload, select all the tasks 
in that workload and deselect the system service tasks such as 
FllACP, MGR..., and QMG.... On the other hand, if you want to 
measure the system resources that a particular FllACP is 
consuming, enable only FllACP and disable all other tasks. 



4.1.5 System Metrics 

Normally system metrics should be enabled with a sample 
interval of 60 seconds. If you want to save logfile space and 
report paper, longer sample intervals may be used. 

4.2 DATA REDUCTION PROCEDURE 

Once you have a logfile on disk or tape, you are ready to read 
the logfile with MDR and reduce the data to a usable perfor- 
mance report. A guide to reading the performance report is 
given in Chapter 5 . 

The data reduction procedure should consist of a number of 
steps methodically performed. A general guideline is to first 

obtain a number of overviews of the system activity during the 
entire measurement period and then print detailed analyses of 
the subset measurement intervals of interest. For example, if 
during an 8 hour shift there were two intervals of peak 
activity, from 9 to 1 1 a.m. and from 2 to 4 p.m., you should 
first run MDR with /L I : to get a system metrics scan of the 
entire 8 hour shift, and then run MDR with /AF and /BF to got a 
report of only the peak morning activity and again with /AF and 
/BF to get only the peak afternoon activity. The general 
procedure is as follows: 

• Run MDR with /LI:0 for entire logfile. 

Identify the intervals of interest and record their 
ondpoints of time using the KWll-P clock timestamps 
printed above the system metrics. 

• Rerun MDR once for each subset measurement interval 
using /AF and /BF with the /LI:2 switch. 
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This will give both system and task summaries. 
Identify the largest consumers of resources and record 
thei r tasknames . 

Rerun MDR with /LI:4 or /LI:5 and /TS for the tasks 
des i red . 

Observe a detailed analysis of the particular tasks 
which consumed the resources and the times when these 
resources were consumed. 
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Chapter 6 
READING THE 
PERFORMANCE REPORT 



5.1 PERFORMANCE REPORT DATA 

When reading this section, refer to Appendix F, which contains 
a sample performance report. 

The performance report consists of four sections: 

• Measurement Parameters 

• System Configuration 

• System Metrics 

• Task Metrics 



5.1.1 Measurement Parameters 

The measurement parameters are read from the Monitor Parameter 
Block (MPB) which is the first block of the logfile. The MDR 
task extracts the information from it and prints the measure- 
ment parameters on the first page of the performance report. 
The items printed are: 

Label . 

Measurement mode. 

Buffer type, partition, number and size. 
Resources selected for System Metrics. 
TI filter device (if solectod). 
Tasks selected for data collection. 
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• Devices selected for data collection. 

• Hooks enabled. 

• MDR command 1 i ne 



5.1.2 System Configuration 

The system configuration information is contained in the 
Information Records and directly follows the MPB in the 
logfile. I f the /SC switch is specified, the MDR task will 
extract the information from these records and print it to the 
logfile. The information printed is: 

• The Pool (DSR) size in bytes and the executive feature 
mask . 

• A list of the partitions in the system when COL was 
activated. 

• A list of the controllers and units in the system when 
COL was activated. 

• A list of the tasks installed in the system when COL 
was activated. 

• A list of the active checkpoint files and their sizes 
when COL was activated. 



5.1.3 System Metr i cs 

The system metrics are system-wide measurements of CPU usage, 
pool usage, the usage of a selected partition, checkpoint file 
usage, and the usage of a selected device. Measurements are 
made for each sampling interval and the results written to the 
logfile. The length of the sampling interval is selected in 
the SMPGEN.CMD procedure. The system metrics are: 

t CPU Usage 

For each sampling interval, counters are kept for the 
total times spent in kernel and idle states. The 
remainder of the sampling interval time is assumed to 
be user state. To depict CPU usage, a histogram is 
printed on the performance report. Each 1% of time 
spent by the CPU in user mode is represented by a 
single letter "U". Each 1% of time spent by the CPU 
in kernel mode is represented by a single letter "K". 
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The user time is left justified and grows from loft to 
right; the kernel time is right justified and grows 
from right to left. If any blank spaces exist in the 
line, they represent CPU idle time. 

• Pool Usage 

At the end of each sampling interval, 
RSX-llM system pool and measures the 
pool in use. The percentage of 
represented by a histogram, where each 
1% of pool usage. 

• Partition Usage 

The user selects a partition to be monitored via the 
COL switch /PR:parnam. At the end of each sampling 
interval, COL scans the partition data structures for 
the selected partition to measure the percentage of 
the memory in use in the partition. The percentage of 
memory used in the partition is represented by a 
histogram, where each "M" represents 1% of partition 
usage . 

• Checkpoint File Usage 

When COL is actiyatod, it scans the checkpoint file 
list and records a list of all active checkpoint files 
and their sizes. 

At the end of each sampling interval, COL scans the 
checkpoint file list and measures the percentage of 
all active checkpoint file space in use. If there is 
more than one checkpoint file, COL sums the space in 
all checkpoint files to compute the percentage. The 
percentage of checkpoint file space used is repre- 
sented by a histogram, where each "C" represents \% of 
checkpoint file space usage. 

t Device Usage 

The user selects a device to be monitored via the COl' 
switch /DV:ddnn. For each sampling interval, COL 
tallies all the I/O request times for the selected 
device to get the percentage of time that the I/O 
device was in use during the sampling interval. The 
percentage of time the device was used is represented 
by a histogram, whore each "D" represents 1% of device 
usage time for the sampling interval. 



COL scans the 
percentage of 
pool used is 
"P" represents 
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In addition, if the device is a Files-11 disk and is 
mounted native, the number of disk blocks used on the 
volume is computed a t the end of the sampling 
interval. The percentage of disk space used is 
represented by a histogram v/here each "B" represents 
1% of the total volume space used. 



For each sampling i nterval , the hi stograms for CPU , pool , 
memory, checkpoint file space, and device are clustered 
together into six successive lines on the report. 

The end of each sampling interval is timestamped and printed in 
two formats: KWll-P time and RSX-llM system time. 

The KWll-P time is printed as two octal numbers: the left 

number is the high order part and the right number is the low 

order part . The corresponding RSX-llM system time is pri nted 
as HRS:MIN:SEC. TENTHS. 

The KWll-P timestamp can be used to: 

• Correlate an individual task report page (which has 
the same form of timestamp) with a particular system 
metri c line. 

• Select a parti cul ar measurement interval of interest 
by rerunn i ng MDR using the /AF and /BF switches. 



The total s for CPU kernel time, CPU idle time and device busy 
time are given for each measurement interval. 

The last i tem in the system metrics section is the " Total Data 
Reduction Period". This is the total time for which data was 
reduced . I f the report was generated using the / AF and / BF 
switches, only the data reduced between /AF and /BF is counted. 



5.1.4 Task Metrics 

Levels of Task Summarization 

The task metrics describe the usage of the resources in the 
system on a task-by-task basis. There are a number of levels 
of summarization available in the performance report, which 
enables the user to choose between a very detailed report or a 
shorter summar i zed report. The levels of s ummar i zat i on and 
their corresponding switches are as follows: 
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9 Individual Task Invocations (/LI:4 or /LI:5) 



An individual task invocation is defined as a single 
run of a task, that is, the time between an executive 

Run Task event and an executive Exit Task event (the 
exact placement of the hooks for these events is 
specified in Appendix A). A complete set of task 
metrics will be printed for each task invocation. If 
most or all tasks in the system are enabled for data 
collection, a report containing individual task 
invocations may be quite long. 

Task by TI Summary (/LI:3) 

In this level of summary, the task metrics for tasks 
with the same generic taskname (see Chapter 2, section 
2.2.2) and the same TI are grouped together when the 
statistics are computed. The task metric s then reveal 
the measurements summed across all tasks with the same 
generic taskname from the same TI. 

Task Summary ( /L I : 2 ) 

In this level of summary, the task metrics for tasks 
with the same generic taskname (see Chapter 2, section 
2.2.2) are grouped together when the statistics are 
computed. The task metrics then reveal the measure- 
ments summed across all tasks with the same generic 
taskname . 

System-Wide Summary (/LI:1) 

I n this level of summary, the task metrics for a 1 1 
tasks in the system that were enabled for data 

collection arc grouped together when the statistics 
are computed . The task metrics then reveal the 
measurements summed across all tasks in the system. 



Task Metric Data 

The following data is presented in the performance report for 
all levels of task summarization. 

• Generic TASK 

The generic taskname (see Chapter 2, Section 2.2.2) is 
printed on the top of the page to identify the task 
for which the data applies. 
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Elapsed Times 



The elapsed time is the time from a Run Task event to 
an Exit Task event. 

Number of Task Invocations 

The Number of Task Invocations is the number of times 
that a Run Task event occurred for the task. If the 
COL task is started while a task is in progress, the 
Run Task event will not be recorded in the logfile for 
that task. When the task exits, an Exit Task event 
will be recorded to the logfile. When MDR reads an 
Exit Task event without a corresponding Run Task 
event, it reports an "incomplete" invocation in the 
Number of Task Invocations line. 

Memory Times 

There are three memory times: 
In (memory) 

- Out ( memory) - includes time waiting for memory on 
initial task load and all time checkpointed 
( wa i t i ng and stopped ) . 

- Wait (memory) - includes time waiting for memory on 
initial task load and time checkpointed (waiting 
only) . 



Memory Size in K Words 
Size of the task region. 
Space-Time Product 

The space- time product is the amount of memory that a 
task uses integrated over the time that the memory wa s 
used. Each increment of memory used (in K words) is 
multiplied by the time (in SECs ) that the increment 
was used, and all products are summed to get the 
space-time product. If a task changes its size via an 
Extend Task directive, the correspond i ng change in 
memory usage is computed. 
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ACP Counts 

The ACP Counts are tallied across all ACPs in the 
system. They are not broken down by separate ACP. 

There are seven categories of ACP functions printed on 
the performance report. They are: 

Access/Deaccess 

These functions are: Access File for Read, Access 
File for Read/Write, Access File for Read/Write/ 
Extend, Deaccess File, Connect Logical Link, and 
Disconnect Logical Link, and Close Out LUN. 

Create/Delete 

These functions are: Create File, Delete File and 
Truncate File. 

Read/Write 

These functions are: Read Virtual Block, Write 
Virtual Block, Receive Message and Transmit 
Message . 

Directory 

These functions are: Find File Name in Directory, 
Enter File Name in Directory and Remove File Name 
from Di rectory . 

File Attribute 

These functions are: Read File Attributes and Write 
Fi 1 e Attributes . 

Extend 

This is the Extend File function. 
- Other 

These functions are all ACP functions other than 
those listed above, such as: Unlock Block, User 
Magtape Control Function and Network Control 
Function. 
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• Memory Residency 

The Memory Residency count is incremented each time a 
task successfully allocates memory for an initial task 
load or for a checkpoint read. 

CPU Time si ices 

A CPU Timeslice is the time between a Load Task 
Context event and a Save Task Context event , minus the 
idle time accrued during that period. Note that if a 
task issues a directive and the processor swi tches to 
kernel mode, the corresponding time in kernel mode is 
charged to the active task's CPU timeslice. Also, if 
an interrupt occurs while a task's context is active, 
the corres pond i ng kernel mode time is charged to the 
active task's CPU timeslice. 

• Initial Loads 

Initial Loads is the number of Initial Task Load 
events for the task . The USAGE times indicate the 
time it took the loader task to load the task ; the 
WAIT times indicate how long a task' s load request was 
in the 1 oader task ' s queue . 

• Checkpoint R+W 

Checkpo i nt R + W is the number of Checkpoint Read and 
Checkpoint Write events for the task. The USAGE times 
i nd i cate the time it took the loader task to check- 
point (read or write) the task. (Note: the USAGE 
times do not indicate how long a task was check- 
po i n t e This information appears under "Memory 
Times" on the task metric page . ) 

• DDnn Ovly Loads 

DDnn Ovly Load s is the number of overlay read ( 1 . LO V ) 
QIOS the task issued to device DDnn. 

• DDnn QIOs 

DDnn QIOs is the number of 1 o g i c a 1 QIOs a task issued 
to device DDnn. Please note the following caveats: 

DDnn Ovly Loads is included in this count, since 
lO.LOV is a Logical block QIO. 
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- Task lO.RVB and lO.WVB (virtual) QIOs which are 
successfully and entirely mapped by the executive 
or FllACP to lO.RLB and lO.WLB (Logical) QIOs are 
i ncl uded in this count. 

- Task lO.RVB and lO.WVB (virtual) QIOs which are 
sent to FllACP, and which are performed by FllACP 
on behalf of the task (partially mapped, multiple 
transfers), are not included in this count. This 
logical block I/O is charged to FllACP. 

- The 10. ATT, lO.DET and lO.KIL QIOs are not included 
in this count. 



USAGE Times 

The USAGE times indicate how long a task used a resource. 



WAIT Times 

The WAIT times indicate how long a task was waiting for the use 
of a resource. 



SERVICE Times 

The SERVICE time is the USAGE time plus WAIT time which 
occurred for each resource request. Note that the mi n imum 
SERVICE time is not necessarily equal to the minimum USAGE time 
plus minimum WAIT time, since the minimum USAGE time may have 
occurred for a different resource request than the resource 
request which had the minimum WAIT time. The same applies to 
the maximum. 



ARRIVALS PER SECOND 

The mean task rate is the number of resource requests issued by 
a task divided by the task's elapsed time . It tells, from a 
task ' s point of view, the rate of resource requests issued by 
a task. The mean system rate is the number of resource 
requests issued by a task divided by the data reduction period. 
It tells, from a resource' s point of view, the rate of resource 
requests issued by a task. 
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Resource Metrics 

For each resource used by a task, the following metrics are 
printed on the report: 

• Count 

The number of times a task used a resource. 

• Total Time 

The total time during which a task used the resource 
(equal to the sum of all resource usage intervals). 

• % Resident Time 

% Resident Time is (Total Time/Resident Time) * 100%. 

• Mi n i mum 

The smallest interval during which a task used a 
resource. 

■ Mean 

The arithmetic average of all resource usage intervals 
for a task. 

• Maximum 

The 1 argest interval during which a task used a 
resource. 

t Coefficient of Variation 

The coefficient of variation is the standard deviation 
f the i nterval s divided by the mean interval . 

• % Resource 

% resource is the total time a task used the resource 
divided by the total time of the Data Reduction Period' 
(total resource time available). 

• Incomplete 

If the logfile does not contain a "complete" set of 
events needed to define an interval , MDR will tally 
the interval as an "incomplete". For example, if MDR 
reads a I/O Done event from the logfile for a certain 
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task and device and there is no corresponding Get I/O 
Packet event for the task and device, MDR will regard 
the I/O interval as an incomplete. Incomplete 
intervals can occur if COL starts data collection 
while an operation (interval) is already in progress. 

The only data recorded for incomplete intervals is the 
count; no timing information is computed since the 
information is not precise. 

Incomplete intervals are printed in lieu of the % 
resource metric if the /IC switch is specified. 
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Chapter 6 

RESOURCES USED 
BY SPM~11M 



The purpose of this section is to give an estimate of the 
resources used by the COL and MDR tasks. 



6.1 RESOURCES USED BY COL 

• CPU 

When a task metric hook is encountered, from 50 to 75 
instructions are executed a t system level ( PR = , 
$STKDP = 0) before returning to the main flow of the 
executive. 

• System Pool 

When the COL task is inactive, about 115 words of 
executive space are used. This is accounted for by 
the hook points (3 words per hook), 4 words added to 
system c ommon , 1 6 wo rd s added to the system stack and 
a dummy hook return routine added to SYSXT. 



When the 
words of 



COL task i s 
system pool 



activated 
are used. 



approximately 215 more 



Physical Memory 



The COL 
memory . 
dynami c 



task occupies 
The COL buffers 
region) can vary 



about 4K words of physical 
(either in a static common or 
from 0.5K words to 32K words. 
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I/O Requests 



The COL task issues a FCS WRITES to write a buffer to 
disk; it issues a QIO$ to write a buffer to magtape. 
The rate of I/O requests generated by COL depends on 
the system activity that COL is tracing. 



RESOURCES USED BY MDR 
Memory 

The code and static data of MDR requires varying 
amounts of memory depending upon which version is 
built. See the TASK IMAGE SIZE in MDR .MAP. 
Additional space is required for I/O buffers and 
dynami c structures which are manipulated within MDR ' s 
virtual address space. MDR will automatically extend 
its virtual space as needed to accommodate these 
structures. Typical ly MDR will require an additional 
8KW for all the dynamic storage. 

Pool 

All MDR I/O is singly buffered, and synchronous, 
minimizing the use of pool. 

I/O 

Each pass of MDR reads a single file and writes to the 
report file. During pass I the RESOURCE. TMP file is 
also being written. Termi nal I/O is used for command 
input, and error reporting. The DRS task will have up 
to 7 files concurrently opened for I/O. 
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Chapter 7 
USAGE NOTES 
SPM-11M 



7. 1 TASKBUILDING COL 

COL must be taskbuilt using the baseline library 
[1 ,1]SYSLIB.0LB (which does not contain FCS routines with ANSI 
or big buffering). 

If COL is taskbuilt with the ANSI or big buffering FCS 
routines, its size may be greater than 4096 words. The result 
will be that when COL is run, it will not be able to create an 
address window (the error received will be COLMSG -- CANNOT 
CREATE BUFFER PARTITION OR ADDRESS WINDOW). 



7.2 COL BUFFERS 

When COL starts up it copies all the TCBs, PCBs, DCBs and UCBs 
to the logfilo. There must be enough buffer space to store al 1 
of those data structures simultaneously , otherwi se COL will 
print the error message COLMSG -- INFORMATION RECORD ALLOCATION 
FAILURE . 

Before COL is left to run unattended for long periods of time, 
COL should bo run for 5 to 10 minutes under a typical heavy or 
peak system workload and the console terminal should be^ 
monitored for the occurrence of overflow errors, i.e., COLMSG 
-- BUFFER OVERFLOW. If buffer overflows occur, the buffer size 
for COL can be increased by using the /BF switch (see Chapter 
3, section 3.2.2). 

Another cause of COL overflows may be small disk file exigent 
sizes. When COL attempts to write a buffer to the I ogf i I e , 
F 1 lACP may have to do an extend file operation before the 
actual data write can be done. The time it takes FllACP to 
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extend a file may bo long, and COL may overflow as a result of 
this. To remedy this situation, two switches have been built 
into COL : 

• Initial File Si ze /IF 

• Extend File Size /EX 

If an estimate can be made of the maximum logfile size before 
COL is run, it is best to preallocate all the logfile space via 
the /IF switch. In this case COL will not need FllACP to do 
any extend file operations during its run and this may prevent 
overflows from occurring. 



7.3 STATE OF SYSTEM AT COL STARTUP TIME 

When COL starts up, it copies the TCBs, PCBs , DCBs and UCBs in 
RSX-llM to the logfile. The MDR task later refers to these 
data structures to derive the necessary context for printing a 
performance report. 

To assure that MDR will have all the context it needs to print 
the report, you should insure that the following conditions are 
satisfied before starting up COL: 

• All tasks installed 

If you want to disable a task for data collection, 
that task must be installed when COL starts up . Al 1 
tasks dynamically installed after COL starts will 
always be enabled for data collection. This means 
that all multiple copies of a multiuser task will 
always be enabled for data collection. 

• All parti ti on s set up 

If you want memory metrics kept for a partition, the 

partition must be set up 

(via SET /MAIN=XYZPAR :m: n :type) before starting COL. 

• All drivers 1 oaded 

If you want the I/O metrics kept for a device-unit, 
the driver managing that device-unit must be loaded 
before starting COL. 

• All devices mounted 

If you want the correct ACP taskname for a mounted 
volume to be printed on the performance report, the 
volume must be mounted before starting COL. Other- 
wise, MDR will print a "pseudo" taskname for the ACP. 
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Example: If the device DKl: is mounted to the FllACP 
task after data collection is in progress for COL, MDR 
will print the pseudo name DK1***ACP on the report. 

• All checkpoint files allocated 

If you want the system metrics for checkpoint file 
usage, be sure to allocate all checkpoint files with 
the ACS command before starting COL. 

7.4 TASK BUILDING MDR 

MDR will run on processors with or without hardware FPP (float- 
ing point processor) support. If your processor does not have 
hardware FPP, it must minimally have hardware EIS instructions. 

You must taskbuild MDR to reflect the type of hardware (FPP or 
EIS) on your processor. You can build MDR either overlaid or 
non-overlaid with both FPP and EIS versions. To build MDR, 
invoke the build command file: 

>@MDRTKB 

This command file will prompt you to build any of the four 
available versions: 

1. FPP support, overlaid 

2. FPP support, non-overlaid 

3. EIS support, overlaid 

4. EIS support, non-overlaid 

You can change certain MDR defaults by editing the taskbuild 
command file produced by MDRTKB.CMD. The MDRTKB.CMD procedure 
will prompt you for changing the defaults. The defaults which 
can be changed are : 

• Number of lines per page in REDUCE. RPT file 

• Default values for /LI switch 

• Default values for /SI switch 

• Default magtape logfilo density (/DE) 

• Default value for /DM switch 
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7.5 USE WITH LAYERED PRODUCTS 

SMP-llM inserts hooks into the RSX-llM executive at standard 
places where the executive does allocations and deallocations 
of resources. 

SPM-llM measures kernel CPU time by hooking the standard 
interrupt save ($INTSV, $INTSE, $INTSC) and system exit 
($DIRXT) points. 

If any layered product or user privileged component uses 
nonstandard techniques for resource allocation or interrupt 
entry , the SPM-llM measurements wi 1 1 be inaccurate. 

For example, DECNET uses a nonstandard interrupt save routine, 
which means the kernel CPU time measurement will be inaccurate. 
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Appendix A 
HOOK RECORD 
DEFINITIONS 



NOTE: All record offsets in this appendix 
are expressed in octal bytes. 

All record lengths are expressed in 
decimal bytes. 



i. 
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1.0 H$CDRP - CALL DIRECTIVE PROCESSOR 



1.1 LOCATION 

DRDSP.MAC 

After $EMTRP: :DIRSV$ 

After $DPLM2::M0V (SP)+,R3 

After 50$: MOV R5,R2 
Follow MOV $HEADR,R4 



1.2 DATA COLLECTION 



1.2.1 Storage Dependencies - 



$TKTCB (Current Task TCB) 
$DICSV (Directive ID Code) 



1.2.2 Record Format 



Hook I.D 



Time St amp 



Taskname (RAD50) 



TI UCB Address 



Die 



12 
14 



1.2.3 Record Length - 
14. bytes. 
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2.0 H$RTSK - REQUEST TASK TO RUN 



2.1 LOCATION 



REQSB.MAC 

After $TSKRP:: 

After 1$: 

Follow MOV 



R2,T.UCB(R0) 



2.2 DATA COLLECTION 

2.2.1 Storage Dependencies 

RO=TCB address 

2.2.2 Record Format - 



Hook I.D. 



Ti mestamp 



Taskname (RAD50) 



TI UCB Address 



Request UIC 




2 



12 
14 



2.2.3 Record Si ze - 
14. bytes. 
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3.0 H$XTSK - TASK EXIT 



f 

3.1 LOCATION 



DREIF.MAC 

After $CEXIT 

After 134$: 

Follow .ENDC 



;P$$OFF 



3.2 DATA COLLECTION 

3.2.1 Storage Dependencies 
$TKTCB=TCB address 

3.2.2 Record Format - 



Hook I.D. 



Ti mestamp 



Tasknamo (RAD50) 



TI UCB Address 



I d 1 e t i m e 




2 



12 
14 



3.2.3 Record Length 
16. bytes. 
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( 



4.0 H$SCTX - SAVE CONTEXT OF TASK 



4.1 LOCATION 



SYSXT.MAC 

After 
Follow 



RESCH 
73$: 



CLR 
MOV 



$RQSCH 

H.GARD (R3) ,R2 



4.2 DATA COLLECTION 

4.2.1 Storage Dependencies - 
$TKTCB (Current Task TCB) 

4.2.2 Record Format - 



Hook I . D 



Ti mestamp 



Taskname (RAD50) 



TI UCB Address 



Id! etime 




2 



12 
14 



4.2.3 Record Length 
1 6 . bytes . 



i 
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5.0 H$LCTX - LOAD CONTEXT OF TASK 



( 



5.1 LOCATION 



SYSXT.MAC 

After RESCH 
After 120$: 
Follow 



CLR $RQSCH 

MOV H.GARD {R2) ,R0 

.ENDC 



5.2 DATA COLLECTION 

5.2.1 Storage Dependencies - 

$TKTCB (TCB address of new task) 



5.2.2 Record Format - 



Hook I.D, 



Ti mestamp 



Taskname (RAD50) 



TI UCB Address 12 



Idletime 14 



5.2.3 Record Length - 
16. bytes. 
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6.0 H$USTP - UNSTOP TASK 



6.1 LOCATION 

REQSB.MAC 
After 
Fol 1 ow 



$EXRQN: :BIT #T 2 . STP *2 ! T2 . STP , T . ST2 ( R ) 
BIG #T2.STP*2!T2.STP,T.ST2(R0) 



6.2 DATA COLLECTION 

6.2.1 Storage Dependencies 
RO=TCB address 

6.2.2 Record Format - 



Hook I.D. 



Timestamp 



Taskname (RAD50) 



TI UCB Address 




2 



12 



6.2.3 Record Length - 
1 2 . bytes . 
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7.0 H$QAST - QUEUE AST TO TASK 



7.1 LOCATION 

REQSB.MAC 

After $QASTT::ADD #T.ASTL,RO 
Follow CAll $SETCR 

7.2 DATA COLLECTION 

7.2.1 Storage Dependencies - 
RO=TCB address 

7.2.2 Record Format - 



Hook I.D. 

Time St amp 2 

( 

Taskname (RAD50) 6 



TI UCB Address 12 



7.2.3 Record Length - 
12. bytes. 
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8.0 H$EXTK - EXTEND TASK 

8.1 LOCATION 

DREXP.MAC 

After $DREXP::TSTB T.I0C(R5) 
Follow 71$: MOV R 1 , P . S I ZE ( RO ) 

8.2 DATA COLLECTION 

8.2.1 Storage Dependencies - 

$TKTCB-TCB address 
RO=PCB address 

8.2.2 Record Format - 

Hook I.D. 
Timestamp 

Taskname {RAD50) 

TI UCB Address 
Main PCB Address 
Task Size 

8.2.3 Record Length - 
16. bytes. 
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2 

6 

12 
14 
16 



9.0 H$QTRP - QUEUE TASK REQUEST FOR PARTITION 

9.1 LOCATION 

REQSB.MAC 

After $TSKRP:: 
After 7$: 

Follow MOV Rl.RO 

9.2 DATA COLLECTION 

9.2.1 Storage Dependencies - 
RO=TCB address 



9.2.2 Record Format - 



Hook I.D. 



Ti mestamp 



Taskname (RAD50) 



TI UCB Address 12 



9.2.3 Record Length - 
12. bytes. 
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10.0 H$QLDR - QUEUE TASK LOAD REQUEST TO LOADER QUEUE 



10.1 LOCATION 



REQSB.MAC 

After $NXTSK: :SAVNR 

After 25$: 

Follow BISB 



-(RO) ,P.BUSY+1 (R5) 



10.2 DATA COLLECTION 

10.2.1 Storage Dependencies - 

R1=TCB address 

10.2.2 Record Format - 



Hook I.D. 



Ti mestamp 



Taskname {RAD50) 



TI UCB Address 




2 



12 



10.2.3 Record Length - 
12. bytes. 
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11.0 H$QCHW - QUEUE CHECKPOINT WRITE REQUEST TO LOADER QUEUE 

f 

11.1 LOCATION 

REQSB.MAC 

After $CHKPT:: 
After 50$: 

Follow BIS #TS.CKP,T.STAT(R1) 

11.2 DATA COLLECTION 

« 

11.2.1 Storage Dependencies - 

Rl =TCB address 

11.2.2 Record Format - 



Hook I.D. 
Ti mestamp 



Taskname (RAD50) 



TI UCB Address 
T. ST2 



11.2.3 Record Format - 
14. bytes. 




2 

6 

12 
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12.0 H$GLDR - GET REQUEST FROM LOADER QUEUE 



12.1 LOCATION 

LOADR.MAC 

After SLOADR : : CAl 1 $SWSTK, 40$ 
Follow 10$ : MOV Rl.LDRTK 



12.2 DATA COLLECTION 

12.2.1 Storage Dependencies 
R1=TCB address 

12.2.2 Record Format - 



Hook I.D, 



Ti mestamp 



Taskname (RAD50) 



TI UCB Address 



T.LDV 



P. MAIN 



P. SIZE 



T.STAT 




2 



12 
14 
16 
20 
22 



12.2.3 Record Format 
20. bytes. 
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13.0 H$FLDR - FINISH LOADER REQUEST 

f 

13.1 LOCATION 

LOADR.MAC 

After $L0ADR::CA11 $SWSTK, 40? 
Follow 84$: CAll $ SWST K , $ LOADR 

13.2 DATA COLLECTION 

13.2.1 Storage Dependencies - 
R5=TCB address 

( 

13.2.2 Record Format - - 

Hook I.D. 

Timestamp 2 

( 

Taskname (RAD50) 6 
TI UCB Address 12 

( 

13.2.3 Record Length - 
12. bytes. 
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14.0 H$CREG - CREATE REGION 



14.1 LOCATION 



DRREG.MAC 

After $DRCRR 

After 74$: 

Follow BIS 



#RS.CRR,R.GSTS(R3) 



14.2 DATA COLLECTION 



14.2.1 Storage Dependencies 



$TKTCB=TCB address 
R4=Region's PCB address 



14.2.2 Record Format - 



Hook ID 



Timest amp 



Taskname (RAD50) 



TI UCB Address 



Main Par. PCB Address 



Region's PCB Address 



P. SIZE 



Region name (RAD50) 



12 



14 



16 



20 



22 



14.2.3 Record Length 
22. bytes. 
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15.0 H$DREG - DELETE REGION 



15.1 LOCATION 



DRREG.MAC 

After $DETRG: :MOV 
Follow 40$: MOV 



A.PCB(R5) ,R0 
P.SUB(RO) , P.SUB(R1 ) 



14.2 DATA COLLECTION 



15.2.1 Storage Dependencies 



$TKTCB=TCB address 
RO=Reg i on' s PCB Address 



15.2.2 Record Format 



Hook ID 



Timest amp 



Taskname (RAD50) 



TI UCB Address 



Region PCB Address 




2 



12 



14 



15.2.3 Record Length 
14. bytes. 
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16.0 H$QDRV - QUEUE I/O PACKET TO DRIVER 



16.1 LOCATION 



DRQIO.MAC 

After $DRQIO:: 
Follow $DRQRQ::MOV 



U.SCB(R5) ,R4 



16.2 DATA COLLECTION 



16.2.1 Storage Dependencies 

R1=IRP address 
R5=UCB address 



16.2.2 Record Format - 



Hook I.D. 



Timestamp 



Taskname (RAD50) 



TI UCB Address 



UCB Address 



Function code 



LUN 



IRP Address 




2 



12 
14 
16 
20 
22 



16.2.3 Record Length - 
20. bytes. 
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17.0 H$GPKT - DRIVER GETS AN I/O PACKET 



17.1 LOCATION 



lOSUB.MAC 

After $GTPKT 
Follow 128$: 



CLC 



17.2 DATA COLLECTION 



17.2.1 Storage Dependencies 

R1=IRP address 
R5=UCB address 



17.2.2 Record Format 



Hook I.D. 



Timestamp 



Taskname (RAD50) 



TI UCB Address 



IRP Address 




2 



12 
14 



17.2.3 Record Length 
14. bytes. 
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18.0 H$IODN - I/O DONE PROCESSING 



18.1 LOCATION 

lOSUB.MAC 

Follow $IODON::MOV 



U. SCB(R5) ,R4 



18.2 DATA COLLECTION 

18.2.1 Storage Dependencies 
R4= SCB Address 

18.2.2 Record Format - 



Hook I . D. 



T i mest amp 



Taskname (RAD50) 



TI UCB Address 



IRP Address 




2 



12 



14 



18.2.3 Record Length 
14. bytes. 
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19.0 H$IOFN - COMPLETE I/O POST PROCESSING 



19.1 LOCATION 



lOSUB.MAC 

Follow $IOFIN:: 



19.2 DATA COLLECTION 

19.2.1 Storage Dependencies 
R3=IRP address 

19.2.2 Record Format - 



Hook I.D. 



Ti mestamp 



Taskname (RAD50) 



TI UCB Address 



IRP Address 





2 



12 
14 



19.2.3 Record Length 
14. bytes. 
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20.0 H$QAC1 - QUEUE I/O PACKET TO AGP 

( 

20.1 LOCATION 

DRQIO.MAC 

After $DRQIO:: 
After FCXIT: 

Follow MOV U.ACP(R5),R0 



* 

20.2 DATA COLLECTION 



20.2.1 Storage Dependencies - 
R1=IRP address 



20.2.2 Record Format - 



Hook I.D, 



Ti mestamp 




2 



Taskname (RAD50) 



TI UCB Address 



UCB Address 



Function Code 



LUN 



IRP Address 



12 
14 
16 
20 
22 



20.2.3 Record Length - 
20. bytes. 
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21.0 H$QAC2 - QUEUE I/O PACKET TO ACP 



21.1 LOCATION 

lOSUB.MAC 

After $GTPKT 
Follow 95$: 



21.2 DATA COLLECTION 

21.2.1 Storage Dependencies 

Rl =IRP address 

21.2.2 Record Format - 



Hook I.D, 



Ti mest amp 



Taskname (RAD50) 



TI UCB Address 



UCB Address 



Function Code 



LUN 



IRP Address 




2 



12 
14 
16 
20 
22 



21.2.3 Record Length - 
20. bytes. 
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22.0 H$GACP - ACP GET PACKET 



22.1 LOCATION 



DISPAT.MAC (FllACP) 

After .START:: 
Follow MOV 



$HEADR,R5 



22.2 DATA COLLECTION 

22.2.1 Storage Dependencies 
R1=IRP Address 

22.2.2 Record Format - 



Hook I.D, 



Ti mestamp 



Taskname (RAD50) 



TI UCB Address 



IRP Address 




2 



12 
14 



22.2.3 Record Length 
14. bytes. 
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23.0 HSDRSV - DIRECTIVE SAVE 

23.1 LOCATION 

SYSXT.MAC 

After $DIRSV:: 

Follow MOV SP,@$HEADR 

23.2 DATA COLLECTION 

23.2.1 Storage Dependencies - 
None 

23.2.2 Routi ne - 

Timestamps system entrance time $BSTIM. 

23.2.3 Record Format - 
None 



24.0 H$INSV - INTERRUPT SAVE 

24.1 LOCATION 

SYSXT.MAC 

After SINTSV: : 

Fol 1 ow MOV SP,(3$HEADR 

24.2 DATA COLLECTION 

24.2.1 Storage Dependencies - 
None 

24.2.2 Routine - 

Timestamps system entrance time $BSTIM. 

24.2.3 Record Format - 
None 
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25.0 H$INS2 - INTERRUPT SAVE 

25.1 LOCATION 

SYSXT.MAC 

After $INTSC:: 

Follow MOV SP,(a$HEADR 

25.2 DATA COLLECTION 

25.2.1 Storage Dependencies - 
None 

25.2.2 Routine - 

Timestamps system entrance time $BSTIM. 

25.2.3 Record Format - 
None 



26.0 H$SYXT - SYSTEM EXITS TO USER TASK 

26.1 LOCATION 

SYSXT.MAC 

After $DIRXT:: 
Follow 5$: 

26.1.1 Storage Dependencies - 
None 

26.1.2 Routine - 

Copies current clock time, subtracts system entrance 
time ($BSTIM), and adds the resulting delta time-to 
the total system time $TSTIM. 

26.1.3 Record Format - 
None 



i 
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27.0 H$EIDL - ENTER EXECUTIVE IDLE LOOP 

f 

27.1 LOCATION 

SYSXT.MAC 

After RESCH: 
After 30$: 

Folow BNE 10$ 

27.2 DATA COLLECTION 

27.2.1 Storage Dependencies - 
Non e 

2 7.2.2 Routine - 

Copies current clock time, subtracts the system f 
entrance time ( $BST IM) , and add s the resulting delta ' 
time to the total system time $TSTIM. Timestamps idle 
entrance time $BIDLE. 

27.2.3 Record Format - 

None 

{ 

28.0 H$XID1 - EXIT EXECUTIVE IDLE LOOP 

28.1 LOCATION 

SYSXT.MAC 

After RESCH: 

Follow 46$: CLRB (Rl) | 

28.2 DATA COLLECTION 

28.2.1 Storage Dependencies - 
None 

28. 2. 2 Routine - 

Copies current clock time, subtracts the idle loop 
entrance time ( $B I DLE ) , and adds the resulting delta 
time to the total idle time $IDLE. Timestamps system 
entrance time $BSTIM. 

28.2.3 Record Format - 

None 1 
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29.0 H$XID2 - EXIT EXECUTIVE IDLE LOOP 

29.1 LOCATION 

SYSXT.MAC 

After $FORKO: : 

Follow BCC $INTXT 

29.2 DATA COLLECTION 

29.2.1 Storage Dependencies - 
None 
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30.0 HSUSER - USER INFORMATION HOOK 



30.1 LOCATION 

QPDR V.MAC 

Follow QPINI 



30.2 DATA COLLECTION 

30.2.1 Storage Dependencies 

R1=IRP address 
R5=UCB address 

30.2.2 Record Format - 



Hook I.D" 



Timestamp 



Tasknamc (RAD50 ) 



n UCB Address" 



Function Code 



LUN 



Q 1 Parameter 1 



QIO ParameteFT 



Q 10 Parameter 3 



QIO Parameter 4 



QIO Parameter 5 



QIO Parameter 5~ 



30.2.3 Record Length 
28. bytes. 




2 



12 
14 
16 
20 
22 
24 
26 
30 
32 
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Appendix B 
MPB DEFINITIONS 



Monitor Parameter Block 

The Monitor Parameter Block (MPB) is the data structure which 
contains the measurement parameters. These measurement 
parameters are defined by invoking the procedure @SMPGEN.CMD, 
whi ch produces : 

The binary MPB file ( f i 1 en ame . MPB ) 

The source MPB file ( f i 1 ename . PAR ) 

The MPB saved answer file (filename.CMD) 

The COL task reads the MPB and initializes its databases from 
the MPB. 

The MPB has the following format and contents: 
Parameter Offset Si ze(wds) Val ues 

MPB ID word (I$MPB) M.PID 1 I$MPB 

Measurement label M.LABL 32. 

Buffer Type M.BTYP 1 DYNAMIC=0 

STATIC=1 

Buffer Count M.BCNT 1 

Buffer Si ze (bytes) M.BSIZ 1 

Buffer Si ze (64b bl k) M.BS64 1 
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Parameter 

Buffer Partition Name 
SYS Partition Name 
Buffer Partition Addr. 
Buffer Partition Size 
Buffer Partition Flags 
Measurement Mode 

Sample Count (Buffers) 
Sample Interval Mag. 
Sample Interval Units 
Repeat Count 
Repeat Interval Mag. 
Repeat Interval Units 
Hook Bit Table 
I/O Selection Word 
Other Devices Sel . Word 
Device CI ass Mask 
Device Selection Mask 
Sys. Metrics Samp. Int. 
Sys . Metrics Partition 
Sys. Metrics Device 
TI Filter Device 
TI Fi 1 ter Device Num. 
MPB Val idation Word 
Task Selection Mask 
Task Selection Table 



Offset 
M.BPAR 
M.BPNM 
M.BPAD 
M.BTSZ 
M.BFLG 
M.MODE 

M.SCNT 

M.SINT 

M.SUNT 

M.RCNT 

M.RINT 

M.RUNT 

M.HTBL 

M. lOS 

M.OTHR 

M.CWIM 

M.CWIS 

M.SAMP 

M.PART 

M.DEVC 

M.TIDV 

M.TINM 

M. VALD 

M.TKS 

M.TTBL 



Si ze( wds) 
2 
2 



Values 



2 
2 



MANUAL=0 

AUT0ST0P=1 
REPEAT=2 



P$$VER 



28. 
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Appendix C 
INFORMATION RECORD 



f 

Information Record 

The Information Record provides system context data which can 
be correlated with the Hook Records to identify tasks, 
partitions, and I/O device- units. 

In addition, there are Information Records which capture 
essential data when COL starts and stops data collection. 



I$SYS - System Common Information 



I$SYS 

Initial Pool Size 



$FMASK 



Sys. Met. Dev. UCB Address 



{ 
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I$TCB - 



Task Control Block 



I$TCB 

I$TCB Record Si ze 



TCB Address 



TCB Contents 



I$PCB - Partition Control Block 



I$PCB 



I$PCB Record Si ze 



PCB Address 



2 
4 



PCB Contents 
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I$DCB - 



Device Control Block 



I$DCB 

I$DCB Record Si ze 



DCB Address 



DCB Contents 



I$UCB - Unit Control Block 



I$UCB 



I$UCB Record Size 



UCB Address 



2 
4 



UCB Contents 
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I$CKP - Checkpoint File Informati 



on 



I$CKP 



CKP. Fi 1 e Device UCB Addr. 



CKP. Fi 1 e Si ze 



I$TMR - Start Data Collection 



I$TMR 


System Time 


(Year) 


System Time 


(Month) 


System Time 


(Day) 


System Time 


( Hour) 


System Time 


(Mi nute) 


System Time 


(Second ) 


System Time 


(Tick) 


Ticks Per Second 


High KWll-P 


Time 


Low KWll-P Time 




2 
4 




2 
4 
6 

10 
12 
14 

16 
20 
22 
24 
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I$STM - 



Stop Data Collection 



I$STM 


n 


Sy s t em 


Time 


^ I e a r ; 


2 


System 


Time 


( nO n t n ; 


4 


System 


Time 


I Day j 


U 


System 


Time 


^ n u r ^ 


1 n 


5y stem 


Time 


(Minute) 


12 


System 


Time 


(Second ) 


14 


System 


Time 


(Tick) 


16 


Ticks 


^er Second 


c u 


High KWll-P 


Time 


22 


Low KWll-P 


Time 


24 


CPU Kernel 


Time (High) 


26 


CPU Kernel 


Time (Low) 




CPU Idle Time (High) 


32 


CPU Id 


1 e Time (Low) 


34 


Device 


Usage Time (High) 


36 


Device 


Usage Time (Low) 


40 
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Appendix D 
SYSTEM METRIC 
RECORD DEFINITIONS 



System Metrics Record 

The System Metrics Record contains data which represents the 
system-wide usage of the CPU, pool, a selected memory 
partition, checkpoint file space, and a selected device. 



7/81 



SYSTEM METRICS RECORD DEFINITIONS 



D-1 



S$MET 



High KWll-P Time 



Low KWll-P Time 



CPU Kernel Time (High) 



CPU Kernel Time (Low) 



CPU Idle Time (High) 



CPU Idle Time (Low) 



# Free Pool Nodes 



Total Free Pool Space (bytes) 



Smallest Pool Node (bytes) 



Largest Pool Node (bytes) 



Main Partition PCB Address 



Number of Subpartitions 



Total Space Used (32W blks) 



Total CKP.File Space 



Total CKP.File Space Used 



UCB Address of Device 



Device Usage Time (High) 



Device Usage Time (Low) 



Free Disk Blocks (High) 



Free Disk Blocks (Low) 



2 
4 

6 

10 

12 

14 

16 

20 

22 

24 

26 

30 

32 

34 

36 

40 

42 

44 

46 

50 
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Appendix E 
LOGFILE FORMAT 



1.0 DISK LOGFILE FORMAT 

A logfile on disk is a Fi1cs-ll file with the following format 



VBN 
1 

N 
N + 1 

2N 



BUFFER 
#1 



BUFFER 
#2 



BUFFER 
#M 
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Each BUFFER has the following general format (byte 
offsets) : 



Record Count 
Overflow Count 
x$xxx 



x$xxx is 1$, H$ or 
S$ record ID. 
See appendices 
A, B, C and D. 



x$xxx 
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All BUFFERS are the same length. The BUFFER size in 512B 
blocks is derived from the BUFFER size in bytes which is 
stored in the MPB in BUFFER #1: 



BUFFER #1 Format (byte offsets) 



Record Count 



Overflow Count 2 



I$MPB 4 Note: 

I$MPB is the 1st record; 

I$SYS is the 2nd record; 

x$xxx is 1$, H$ or S$ 
record I D . 
See appendices 
A, B , C and D. 



BUFFER Size (bytes) 4+M.BSIZ 



I$SYS 



x$xxx 



Unused 5pac 




/ / 

////// / / LA 



n,,rrrn • /ui i.\ BUFFER s i z e (bytes) 
BUFFER size (blocks) = g-y^ ^ 
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2.0 MAGTAPE LOGFILE FORMAT 



A magtape can contain one or more logfiles. Each BUFFER is 
terminated by an IRQ. Each logfile is terminated by a tape 
mark (EOF). The magtape is terminated by a double tape mark 
(EOF EOF). Each BUFFER has the same format as for disk. 



BUFFER 

#1 



BUFFER 
#M1 



EOF 



end of logfile #1 



BUFFER 
#1 



BUFFER 
#Mn 



EOF 



end of logfile #n 
end of tape 
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3.0 FCS LOGFILE FORMAT 



The CLF utility task can be used to convert a logfilo from the 
formats specified in section 1.0 and 2.0 to a file containing a 
stream of variable length FCS records. Each FCS record 
contains one record of type H$xxxx, I$xxxx or S$xxxx. The 
first word of each record contains the record ID, H$xxxx, 
I$xxxx or S$xxxx. The record formats are specified in 
Appendices A, B, C and D. 

See Chapter 3, Section 3.2.5 for using CLF. 
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Appendix F 
EXAMPLE PERFORMANCE 
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Appendix G 
EXAMPLE SMPGEN 



6 



f 




>SET /UIC-Cllf23 

>eSMPGEN 
>'f 

>»«*« Software Monitor Parameter GENeratiorr command file *#* 
>{ 

>;««« t^ersion 1 **t 
>} 

>fCopyriaht (C) 1981 Diaital Eduipment Corporationt Maynardf Mass. 

>> 

>i 

> r Initialize default parameters 
>f 

>« READ SAVED ANSWER FILE FOR DEFAULT ANSWERS? CY/N3SN 

>'f 

>i Select parameter cateSoryj tape <ese> for help 
>f 

>« ENTER PARAMETER CATEGORY CS3t 

>» 

>; LEGAL PARAMETER CATEGORIES ARE : 

>f HOOK TASK MODE LABEL 

>i BUFFER DEVICE SYSTEM DONE 

>'f 

>* ENTER PARAMETER CATEGORY tSlX HOOK 
>i 

>r Select/deselect hook- points 
>) 

>« CPU USAGE HOOKS? [Y/N3:Y 

>« MEMORY USAGE HOOKS? CY/N3:N 

>» I/O DEVICE USAGE HOOKS? CY/N3:Y 

>5 

>» Select parameter catesiorut tape <esc> for help 

>; 

>« ENTER PARAMETER CATEGORY CS]5 BUFFER 
>5 

>» Setup buffer management parameter? tape <esc> for help 
>5 

>« ENTER BUFFER TYPE CD;DYNAMIC] CS R:0-73: 

>* ENTER NAME OF BUFFER MAIN (SYS) PARTITION CDtGEN] CS R:0-63: 
>* ENTER NAME OF BUFFER COMMON/REGION CDJTRCPAR3 CS R:0-63 : 
>« ENTER NUMBER OF BUFFERS CD R:2.-8. D:2.3: 3 
>« ENTER BUFFER SIZE IN 512B BLOCKS CD RJ».-16. DtS.i: 6 

>' .» 

>i Select parameter catedorar tape <esc> for help 

>} 

># ENTER PARAMETER CATEGORY CS3J TASK* 
>f 

>f Select/deselect tasks to he traced 
>! 

>« DO YOU WANT TO TRACE ALL TASKS? CY/NISN 

>* DO YOU WANT TO SPECIFY THE TASKS NOT TO TRACE? CY/N3SY 
>i 

>i Enter one tasknsme per line. Terminate list ba <CR>. 

> » 

>« ENTER NAME OF TASK NOT TO TRACE ZSlt FUACP 
>« ENTER NAME OF TASK NOT TO TRACE CS]t HCR... 
>* ENTER NAME OF TASK NOT TO TRACE CS] : QMG. . . 
>* ENTER NAME OF TASK NOT TO TRACE CS]t LPPO 
>« ENTER NAME OF TASK NOT TO TRACE CSl*. 
>'f 

>? Select parameter cateaoru» type <esc> for help 
> I 

>« ENTER PARAMETER CATEGORY ISlt DEVICE 
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>« DO YOU WANT TO COLLECT DATA FOR ALL DEVICES? CY/N3IN 

>i 

>} Select device tupes to be traced 

>* TRACE DISK (DIRECTORY DEVICE) I/O ACTIVITY? CY/NaSY 
>* TRACE TAPE (SEQUENTIAL DEVICE) I/O ACTIVITY? CY/N3SY 
># TRACE TERMINAL I/O ACTIVITY? CY/NKN 
>« TRACE ALL OTHER DEVICES I/O ACTIVITY? CY/NJ :N 

>S 

>f Select parameter c3te3or<:<> tape <esc> for help 

>'f 

>« ENTER PARAMETER CATEGORY CS3: MODE 

>i 

>r Define data collection noder type <esc> for help 
>} 

>« ENTER MODE CDJMANUAL] CS RJ0.-8.3: 

>» 

>5 

>; LEGAL MODES ARE: 

>i MANUAA- AUTOSTOP REPEAT 

>J 

>« ENTER MODE CDJMANUAL3 CS RJ0.-8.3: AUTOSTOP 

>» ENTER SAMPLE TYPE CS KtQ-61'. 

>{ 

>i LEGAL SAMPLE TYPES ARES 
>J 

>} BUFFER TIME 

> f 

>« ENTER SAMPLE TYPE CS R50-63; TIME 

>« ENTER SAMPLING INTERVAL TIME UNIT CDtMINl CS RSO-33; HR 
>« ENTER SAMPLING INTERVAL IN HRS CD R: 1 .-10000. DJ1.3J 2 

> i 

>f Select parameter catefloru » tape <esc> for help 

>5 

>« ENTER PARAMETER CATEGORY CS3: SYSTEM 
>l 

>» Select SHSteiii metrics 

>« DO YOU WANT THE SYSTEM-WIDE METRICS? CY/N3 J Y 

>« ENTER SYSTEM METRICS SAMPLING INTERVAL (SECS) CD R:15. -28800. 0560.3} 120. 
>i 

>} Select parameter c3teaora» tape <esc> for help 
>i 

>« ENTER PARAMETER CATEGORY CS3! LABEL 
>» 

>5 Define 1 to 63 character label strina» tape <esc> for help 
>* 

>« ENTER MPB LABEL CS RtO-633: THIS' IS A SAMPLE MPB GENERATION 
>5 

>» Select parameter cateSora» tape <esc> for help 
- >} 

>« ENTER PARAMETER CATEGORY CS3: DONE 
>» 

>f Write saved answer file and parameter source file 

>f Enter <esc> if no output file is desired 

>} 

>« ENTER NAME OF SAVED ANSWER FILE CD ! TRACE . CMD3 CS3: SAMPLE, CMD 
>« ENTER NAME OF PARAMETER SOURCE FILE CD : TRACE . PAR3 CS3S SAMPLE. PAR 
>MAC- SAMPLE = Cll,103RSXMC.Cllf23HKMAC.CH»23SAMPLE.PAR 
>TKB ePARBLD 

>PIP SAMPLE. OB J f«/DE, PARBLD.CMD J « 

>e <EOF> 

> 
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